Merge branch 'main' into translation-module-convenience

Author: n-o-u-r-h-a-n

docs/release_notes.md

@@ -13,6 +13,7 @@
 ### ✨ New Functionality
 
 - [Orchestration] Added new models for `OrchestrationAiModel`: `SONAR`,`SONAR_PRO`.
+- [Orchestration] Convenience for adding the `metadata_params` option to grounding calls.
 
 ### 📈 Improvements
 

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

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(

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

pom.xml

@@ -71,7 +71,7 @@
     <javaparser.version>3.27.1</javaparser.version>
     <jsonschema-generator.version>4.38.0</jsonschema-generator.version>
     <jackson.version>2.20.1</jackson.version>
-    <logback.version>1.5.20</logback.version>
+    <logback.version>1.5.21</logback.version>
     <!-- conflicts resolution -->
     <micrometer.version>1.16.0</micrometer.version>
     <json.version>20250517</json.version>
@@ -289,7 +289,7 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-jar-plugin</artifactId>
-          <version>3.4.2</version>
+          <version>3.5.0</version>
         </plugin>
         <plugin>
           <groupId>com.sap.cloud.sdk.datamodel</groupId>

sample-code/spring-app/README.md

@@ -5,6 +5,29 @@
 Sample code to demonstrate the usage of the SAP AI SDK.
 Also used as basis for running E2E tests.
 
+## Prerequisites
+
+Before running the application, ensure the following prerequisites are met:
+
+- Java 17 or higher
+- Maven 3.8 or higher
+- Credentials for [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core) service configured
+- Deployments of the following models in the `default` resource group:
+  - `gpt-4o-mini`
+  - `text-embedding-3-small`
+
+### Setting Up Credentials for SAP AI Core
+
+To set up credentials for the AI Core service:
+
+- Follow the instruction at [Connecting to AI Core](https://sap.github.io/ai-sdk/docs/java/guides/connecting-to-ai-core) to create a service key for the AI Core service.
+- Add the service key content either to a `.env` file in the sample app directory or directly to the `AI_CORE_SERVICE_KEY` environment variable.
+
+### Deploying Generative AI Models in SAP AI Core
+
+To deploy `gpt-4o-mini` and `text-embedding-3-small` models, follow the instructions at:
+[Create a Deployment for a Generative AI Model](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-deployment-for-generative-ai-model-in-sap-ai-core)
+
 ## Build and Run the Sample App
 
 Before you can run the sample app, you need to install the AI SDK into your local Maven repository:
@@ -15,13 +38,7 @@ Before you can run the sample app, you need to install the AI SDK into your loca
 > The sample app uses the latest state of the SDK, so make sure to install the SDK after pulling a new version via Git.
 > Alternatively, you check out one of the release tags of the repository, e.g. `git fetch --all --tags && git checkout rel/1.1.0`. 
 
-Next, you'll need to set up credentials for the AI Core service: 
-
-* Follow [these instructions](https://sap.github.io/ai-sdk/docs/java/guides/connecting-to-ai-core) to create a service key for the AI Core service.
-
-  ⚠️ Put the `.env` file in the sample app directory.
-
-Finally, you can start the sample app:
+Start the sample app:
 
 * Run `mvn spring-boot:run` from the sample app directory.
 

sample-code/spring-app/pom.xml

@@ -34,8 +34,8 @@
   <properties>
     <project.rootdir>${project.basedir}/../../</project.rootdir>
     <spring-boot.version>3.5.7</spring-boot.version>
-    <logback.version>1.5.20</logback.version>
-    <cf-logging.version>3.8.6</cf-logging.version>
+    <logback.version>1.5.21</logback.version>
+    <cf-logging.version>4.0.0</cf-logging.version>
     <apache-tomcat-embed.version>11.0.13</apache-tomcat-embed.version>
     <!-- Skip end-to-end tests by default, can be overridden with -DskipTests=false -->
     <skipTests>true</skipTests>

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

@@ -376,8 +376,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)

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