Merge branch 'main' into docs/adr-logging

Jonas-Isr · web-flow · commit c772c5af32f4 · 2025-11-24T14:39:03.000+01:00
diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml
@@ -6,7 +6,7 @@ updates:
     directory: '/'
     schedule:
       interval: weekly
-      time: '02:00'
+      time: '23:00'
       timezone: 'Europe/Berlin'
     open-pull-requests-limit: 5
     commit-message:
diff --git a/.github/workflows/dependabot-automerge.yaml b/.github/workflows/dependabot-automerge.yaml
@@ -3,7 +3,7 @@ name: "Dependabot Auto-Merge"
 on:
   workflow_dispatch:
   schedule:
-    - cron: '00 04 * * Mon' # trigger every Monday at 04:00 a.m., as our dependabot is configured to raise PRs every Monday at 2:00 a.m.
+    - cron: '00 01 * * Tue' # trigger every Tuesday at 01:00 a.m., as our dependabot is configured to raise PRs every Monday at 23:00 p.m.
 
 env:
   DEPENDABOT_GROUPS: |
diff --git a/core-services/document-grounding/src/main/java/com/sap/ai/sdk/grounding/model/S3PipelineMinimalResponse.java b/core-services/document-grounding/src/main/java/com/sap/ai/sdk/grounding/model/S3PipelineMinimalResponse.java
@@ -207,7 +207,7 @@ public void setType(@Nonnull final TypeEnum type) {
    */
   @Nonnull
   public S3PipelineMinimalResponse _configuration(
-      @Nonnull final S3ConfigurationMinimal _configuration) {
+      @Nullable final S3ConfigurationMinimal _configuration) {
     this._configuration = _configuration;
     return this;
   }
@@ -227,7 +227,7 @@ public S3ConfigurationMinimal getConfiguration() {
    *
    * @param _configuration The _configuration of this {@link S3PipelineMinimalResponse}
    */
-  public void setConfiguration(@Nonnull final S3ConfigurationMinimal _configuration) {
+  public void setConfiguration(@Nullable final S3ConfigurationMinimal _configuration) {
     this._configuration = _configuration;
   }
 
@@ -377,14 +377,7 @@ private String toIndentedString(final java.lang.Object o) {
    */
   public static Builder create() {
     return (id) ->
-        (status) ->
-            (type) ->
-                (_configuration) ->
-                    new S3PipelineMinimalResponse()
-                        .id(id)
-                        .status(status)
-                        .type(type)
-                        ._configuration(_configuration);
+        (status) -> (type) -> new S3PipelineMinimalResponse().id(id).status(status).type(type);
   }
 
   /** Builder helper class. */
@@ -415,19 +408,8 @@ public interface Builder2 {
      * Set the type of this {@link S3PipelineMinimalResponse} instance.
      *
      * @param type The type of this {@link S3PipelineMinimalResponse}
-     * @return The S3PipelineMinimalResponse builder.
-     */
-    Builder3 type(@Nonnull final TypeEnum type);
-  }
-
-  /** Builder helper class. */
-  public interface Builder3 {
-    /**
-     * Set the _configuration of this {@link S3PipelineMinimalResponse} instance.
-     *
-     * @param _configuration The _configuration of this {@link S3PipelineMinimalResponse}
      * @return The S3PipelineMinimalResponse instance.
      */
-    S3PipelineMinimalResponse _configuration(@Nonnull final S3ConfigurationMinimal _configuration);
+    S3PipelineMinimalResponse type(@Nonnull final TypeEnum type);
   }
 }
diff --git a/core-services/document-grounding/src/main/java/com/sap/ai/sdk/grounding/model/SFTPPipelineMinimalResponse.java b/core-services/document-grounding/src/main/java/com/sap/ai/sdk/grounding/model/SFTPPipelineMinimalResponse.java
@@ -208,7 +208,7 @@ public void setType(@Nonnull final TypeEnum type) {
    */
   @Nonnull
   public SFTPPipelineMinimalResponse _configuration(
-      @Nonnull final SFTPConfigurationMinimal _configuration) {
+      @Nullable final SFTPConfigurationMinimal _configuration) {
     this._configuration = _configuration;
     return this;
   }
@@ -228,7 +228,7 @@ public SFTPConfigurationMinimal getConfiguration() {
    *
    * @param _configuration The _configuration of this {@link SFTPPipelineMinimalResponse}
    */
-  public void setConfiguration(@Nonnull final SFTPConfigurationMinimal _configuration) {
+  public void setConfiguration(@Nullable final SFTPConfigurationMinimal _configuration) {
     this._configuration = _configuration;
   }
 
@@ -380,14 +380,7 @@ private String toIndentedString(final java.lang.Object o) {
    */
   public static Builder create() {
     return (id) ->
-        (status) ->
-            (type) ->
-                (_configuration) ->
-                    new SFTPPipelineMinimalResponse()
-                        .id(id)
-                        .status(status)
-                        .type(type)
-                        ._configuration(_configuration);
+        (status) -> (type) -> new SFTPPipelineMinimalResponse().id(id).status(status).type(type);
   }
 
   /** Builder helper class. */
@@ -418,20 +411,8 @@ public interface Builder2 {
      * Set the type of this {@link SFTPPipelineMinimalResponse} instance.
      *
      * @param type The type of this {@link SFTPPipelineMinimalResponse}
-     * @return The SFTPPipelineMinimalResponse builder.
-     */
-    Builder3 type(@Nonnull final TypeEnum type);
-  }
-
-  /** Builder helper class. */
-  public interface Builder3 {
-    /**
-     * Set the _configuration of this {@link SFTPPipelineMinimalResponse} instance.
-     *
-     * @param _configuration The _configuration of this {@link SFTPPipelineMinimalResponse}
      * @return The SFTPPipelineMinimalResponse instance.
      */
-    SFTPPipelineMinimalResponse _configuration(
-        @Nonnull final SFTPConfigurationMinimal _configuration);
+    SFTPPipelineMinimalResponse type(@Nonnull final TypeEnum type);
   }
 }
diff --git a/core-services/document-grounding/src/main/resources/spec/grounding.yaml b/core-services/document-grounding/src/main/resources/spec/grounding.yaml
@@ -1652,7 +1652,6 @@ components:
         - type: object
           required:
             - type
-            - configuration
           properties:
             type:
               type: string
@@ -1670,7 +1669,6 @@ components:
         - type: object
           required:
             - type
-            - configuration
           properties:
             type:
               type: string
diff --git a/docs/release_notes.md b/docs/release_notes.md
@@ -12,7 +12,8 @@
 
 ### ✨ New Functionality
 
--[Orchestration] Added new models for `OrchestrationAiModel`: `SONAR`,`SONAR_PRO`.
+- [Orchestration] Added new models for `OrchestrationAiModel`: `SONAR`,`SONAR_PRO`.
+- [Orchestration] Convenience for adding the `metadata_params` option to grounding calls.
 
 ### 📈 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
@@ -11,6 +11,7 @@
 import java.util.List;
 import java.util.Map;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import lombok.Setter;
 import lombok.experimental.Accessors;
 import lombok.val;
@@ -31,6 +32,8 @@ public class Grounding implements GroundingProvider {
   private List<GroundingModuleConfigConfigFiltersInner> filters =
       List.of(DocumentGroundingFilter.create().dataRepositoryType(DataRepositoryType.VECTOR));
 
+  @Nullable private List<String> metadataParams = null;
+
   @Setter(onMethod_ = {@Nonnull})
   private TypeEnum documentGroundingService = TypeEnum.DOCUMENT_GROUNDING_SERVICE;
 
@@ -60,6 +63,19 @@ public Grounding filters(@Nonnull final GroundingModuleConfigConfigFiltersInner.
     return this;
   }
 
+  /**
+   * Set which metadataParams are used in the grounding response.
+   *
+   * @param metadataParams List of metadataParams to set.
+   * @return The modified grounding configuration.
+   * @since 1.13.0
+   */
+  @Nonnull
+  public Grounding metadataParams(@Nonnull final String... metadataParams) {
+    this.metadataParams = List.of(metadataParams);
+    return this;
+  }
+
   /**
    * Create a prompt with grounding parameters included in the message.
    *
@@ -86,8 +102,10 @@ public GroundingModuleConfig createConfig() {
                 GroundingModuleConfigConfigPlaceholders.create()
                     .input(List.of("userMessage"))
                     .output("groundingContext"))
-            .filters(filters);
+            .filters(filters)
+            .metadataParams(metadataParams);
 
+    // metadata_params field is not allowed for data repository type: `help.sap.com`
     if (filters.contains(
         DocumentGroundingFilter.create().dataRepositoryType(DataRepositoryType.HELP_SAP_COM))) {
       groundingConfigConfig.setMetadataParams(null);
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
@@ -268,6 +268,28 @@ void testGrounding() throws IOException {
         postRequestedFor(urlPathEqualTo("/v2/completion")).withRequestBody(equalToJson(request)));
   }
 
+  @Test
+  void testGroundingWithConvenience() throws IOException {
+    stubFor(
+        post(urlPathEqualTo("/v2/completion"))
+            .willReturn(
+                aResponse()
+                    .withBodyFile("groundingResponse.json")
+                    .withHeader("Content-Type", "application/json")));
+
+    var dbFilters = DocumentGroundingFilter.create().dataRepositoryType(DataRepositoryType.VECTOR);
+
+    var groundingConfig = Grounding.create().metadataParams("foo", "bar").filters(dbFilters);
+    var prompt = groundingConfig.createGroundingPrompt("Hello, what do you know?");
+    var configWithGrounding = config.withGrounding(groundingConfig);
+
+    final var response = client.chatCompletion(prompt, configWithGrounding);
+
+    final String request = fileLoaderStr.apply("groundingRequestMetadata.json");
+    verify(
+        postRequestedFor(urlPathEqualTo("/v2/completion")).withRequestBody(equalToJson(request)));
+  }
+
   @Test
   void testGroundingWithHelpSapCom() throws IOException {
     stubFor(
diff --git a/orchestration/src/test/resources/groundingRequestMetadata.json b/orchestration/src/test/resources/groundingRequestMetadata.json
@@ -0,0 +1,51 @@
+{
+  "config" : {
+    "modules" : {
+      "prompt_templating" : {
+        "prompt" : {
+          "template" : [ {
+            "content" : "{{?userMessage}} Use the following information as additional context: {{?groundingContext}}",
+            "role" : "user"
+          } ],
+          "defaults" : { },
+          "tools" : [ ]
+        },
+        "model" : {
+          "name" : "gpt-4o",
+          "version" : "latest",
+          "params" : {
+            "max_tokens" : 50,
+            "temperature" : 0.1,
+            "frequency_penalty" : 0,
+            "presence_penalty" : 0,
+            "top_p" : 1,
+            "n" : 1
+          },
+          "timeout" : 600,
+          "max_retries" : 2
+        }
+      },
+      "grounding" : {
+        "type" : "document_grounding_service",
+        "config" : {
+          "filters" : [ {
+            "data_repositories" : [ "*" ],
+            "data_repository_type" : "vector",
+            "data_repository_metadata" : [ ],
+            "document_metadata" : [ ],
+            "chunk_metadata" : [ ]
+          } ],
+          "placeholders" : {
+            "input" : [ "userMessage" ],
+            "output" : "groundingContext"
+          },
+          "metadata_params" : [ "foo", "bar" ]
+        }
+      }
+    }
+  },
+  "placeholder_values" : {
+    "userMessage" : "Hello, what do you know?"
+  },
+  "messages_history" : [ ]
+}
diff --git a/pom.xml b/pom.xml
@@ -77,7 +77,7 @@
     <json.version>20250517</json.version>
     <snakeyaml.version>2.5</snakeyaml.version>
     <!-- Formatting -->
-    <spotless.version>3.0.0</spotless.version>
+    <spotless.version>3.1.0</spotless.version>
     <spotless.skip>false</spotless.skip>
     <!--  Quality assurance  -->
     <enforcer.skip>false</enforcer.skip>
@@ -753,7 +753,7 @@ https://gitbox.apache.org/repos/asf?p=maven-pmd-plugin.git;a=blob_plain;f=src/ma
       <plugin>
         <groupId>com.github.spotbugs</groupId>
         <artifactId>spotbugs-maven-plugin</artifactId>
-        <version>4.9.8.1</version>
+        <version>4.9.8.2</version>
         <configuration>
           <includeFilterFile>${project.rootdir}/.pipeline/spotbugs.xml</includeFilterFile>
           <!-- Exclude generated clients -->
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
@@ -380,8 +380,12 @@ public OrchestrationChatResponse grounding(
             .searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(1))
             .addDocumentMetadataItem(documentMetadata);
 
-    val groundingConfig = Grounding.create().filters(databaseFilter);
-    val prompt = groundingConfig.createGroundingPrompt(userMessage);
+    val groundingConfig = Grounding.create().filters(databaseFilter).metadataParams("*");
+    val prompt =
+        groundingConfig
+            .createGroundingPrompt(userMessage)
+            .messageHistory(
+                List.of(Message.system("Add in the response all metadata from grounding.")));
     val maskingConfig = // optional masking configuration
         DpiMasking.anonymization()
             .withEntities(DPIEntities.SENSITIVE_DATA)
diff --git a/sample-code/spring-app/src/test/java/com/sap/ai/sdk/app/controllers/OrchestrationTest.java b/sample-code/spring-app/src/test/java/com/sap/ai/sdk/app/controllers/OrchestrationTest.java
@@ -209,6 +209,9 @@ void testGrounding() {
     assertThat(result.getIntermediateResults().getGrounding().getData()).isNotNull();
     assertThat(result.getIntermediateResults().getGrounding().getMessage())
         .isEqualTo("grounding result");
+    var groundingData =
+        (Map<String, String>) result.getIntermediateResults().getGrounding().getData();
+    assertThat(groundingData.get("grounding_result")).contains("metadata");
 
     var maskingResult = result.getIntermediateResults().getInputMasking();
     assertThat(maskingResult.getMessage()).isNotEmpty();
