Merge remote-tracking branch 'origin/main' into grounding-client

# Conflicts:
#	pom.xml

Author: a-d

.pipeline/checkstyle-suppressions.xml

@@ -8,9 +8,12 @@
   <!-- Suppress generated clients -->
   <suppress files="[/\\]core[/\\]client[/\\]" checks=".*"/>
   <suppress files="[/\\]core[/\\]model[/\\]" checks=".*"/>
+  <suppress files="[/\\]openai[/\\]generated[/\\]model[/\\]" checks=".*"/>
   <suppress files="[/\\]orchestration[/\\]model[/\\]" checks=".*"/>
   <suppress files="[/\\]grounding[/\\]api[/\\]" checks=".*"/>
   <suppress files="[/\\]grounding[/\\]model[/\\]" checks=".*"/>
   <!-- Suppress TODOs -->
   <suppress files="OpenAiChatMessage.java" checks="TodoComment" lines="257,7" />
+  <suppress files="ChatCompletionResponseMessage.java" checks="TodoComment" lines="53,34" />
+  <suppress files="CreateChatCompletionRequest.java" checks="TodoComment" lines="73,47" />
 </suppressions>

README.md

@@ -155,8 +155,19 @@ For SAP internal development, you can also use `SNAPSHOT` builds from the [inter
 
 ### _"How to add a custom header to AI Core requests?"_
 
-Create a [HeaderProvider](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/http-destinations#about-headerproviders).
+The AI SDK leverages the destination concept from the SAP Cloud SDK to manage the connection to AI Core.
+This opens up a wide range of possibilities to customize the connection, including adding custom headers.
 
+```java
+var service = new AiCoreService();
+var service = service.withBaseDestination(
+        DefaultHttpDestination.fromDestination(service.getBaseDestination())
+          .header("my-header-key", "my-header-value")
+          .build()
+);
+```
+
+For more information, please refer to the [AI Core connectivity guide](./docs/guides/CONNECTING_TO_AICORE.md) and the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/http-destinations).
 
 ### _"There's a vulnerability warning `CVE-2021-41251`?"_
 

core/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <groupId>com.sap.ai.sdk</groupId>
     <artifactId>sdk-parent</artifactId>
-    <version>1.3.0-SNAPSHOT</version>
+    <version>1.4.0-SNAPSHOT</version>
   </parent>
   <artifactId>core</artifactId>
   <name>AI Core client</name>

docs/guides/CONNECTING_TO_AICORE.md

@@ -6,6 +6,7 @@
     - [Providing a Service Binding Locally](#providing-a-service-binding-locally)
     - [Using the `AICORE_SERVICE_KEY` Environment Variable](#using-the-aicore_service_key-environment-variable)
 - [Using a Destination from the BTP Destination Service](#using-a-destination-from-the-btp-destination-service)
+- [Creating a Custom Destination](#creating-a-custom-destination)
 
 
 The AI SDK uses the [`Destination` concept of the SAP Cloud SDK](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service) to connect to AI Core.
@@ -152,4 +153,23 @@ new DeploymentApi(aiCoreService);
 > The `destination` obtained from BTP destination service will expire once the contained OAuth2 token expires.
 > Please run the above code for each request to ensure the destination is up-to-date.
 > Destinations are cached by default, so this does not come with a performance penalty.
-> To learn more, see the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service).
+> To learn more, see the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service).
+
+## Creating a Custom Destination
+
+If the above options are not suitable for your use case (e.g. because you are obtaining the credentials in a completely different way), you can also use a custom-built destination:
+
+```java
+var destination = OAuth2DestinationBuilder
+    .forTargetUrl("https://<ai-api-url>")
+    .withTokenEndpoint("https://<xsuaa-url>/oauth/token")
+    .withClient(new ClientCertificate("<cert>", "<key>", "<clientid>"), OnBehalfOf.TECHNICAL_USER_PROVIDER)
+    .build();
+
+AiCoreService aiCoreService = new AiCoreService().withBaseDestination(destination);
+```
+
+The above example assumes you are using a client certificate for authentication and have stored the relevant credentials somewhere.
+You are free to use X509 certificates (also via the Zero Trust Identity Service) or a client secret.
+
+For more details, refer to the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service).

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -12,6 +12,8 @@
     - [Data Masking](#data-masking)
     - [Grounding](#grounding)
     - [Stream chat completion](#stream-chat-completion)
+    - [Add images and multiple text inputs to a message](#add-images-and-multiple-text-inputs-to-a-message)
+    - [Set a Response Format](#set-a-response-format)
     - [Set Model Parameters](#set-model-parameters)
     - [Using a Configuration from AI Launchpad](#using-a-configuration-from-ai-launchpad)
 
@@ -300,6 +302,73 @@ Note, that only user and system messages are supported for multiple text inputs.
 Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OrchestrationService.java).
 
 
+## Set a Response Format
+
+It is possible to set the response format for the chat completion. Available options are using `JSON_OBJECT`, `JSON_SCHEMA`, and `TEXT`, where `TEXT` is the default behavior.
+
+### JSON_OBJECT
+
+Setting the response format to `JSON_OBJECT` tells the AI to respond with JSON, i.e., the response from the AI will be a string consisting of a valid JSON. This does, however, not guarantee that the response adheres to a specific structure (other than being valid JSON).
+
+```java
+var template = Message.user("What is 'apple' in German?");
+var templatingConfig =
+        Template.create()
+                .template(List.of(template.createChatMessage()))
+                .responseFormat(
+                        ResponseFormatJsonObject.create()
+                                .type(ResponseFormatJsonObject.TypeEnum.JSON_OBJECT));
+var configWithTemplate = llmWithImageSupportConfig.withTemplateConfig(templatingConfig);
+
+var prompt =
+        new OrchestrationPrompt(
+                Message.system(
+                        "You are a language translator. Answer using the following JSON format: {\"language\": ..., \"translation\": ...}"));
+var response = client.chatCompletion(prompt, configWithTemplate).getContent();
+```
+Note, that it is necessary to tell the AI model to actually return a JSON object in the prompt. The result might not adhere exactly to the given JSON format, but it will be a JSON object.
+
+
+### JSON_SCHEMA
+
+If you want the response to not only consist of valid JSON but additionally adhere to a specific JSON schema, you can use `JSON_SCHEMA`. in order to do that, add a JSON schema to the configuration as shown below and the response will adhere to the given schema.
+
+```java
+var template = Message.user("Whats '%s' in German?".formatted(word));
+var schema =
+        Map.of(
+                "type",
+                "object",
+                "properties",
+                Map.of(
+                        "language", Map.of("type", "string"),
+                        "translation", Map.of("type", "string")),
+                "required",
+                List.of("language", "translation"),
+                "additionalProperties",
+                false);
+
+// Note, that we plan to add more convenient ways to add a JSON schema in the future.
+var templatingConfig =
+        Template.create()
+                .template(List.of(template.createChatMessage()))
+                .responseFormat(
+                        ResponseFormatJsonSchema.create()
+                                .type(ResponseFormatJsonSchema.TypeEnum.JSON_SCHEMA)
+                                .jsonSchema(
+                                        ResponseFormatJsonSchemaJsonSchema.create()
+                                                .name("translation_response")
+                                                .schema(schema)
+                                                .strict(true)
+                                                .description("Output schema for language translation.")));
+var configWithTemplate = llmWithImageSupportConfig.withTemplateConfig(templatingConfig);
+
+var prompt = new OrchestrationPrompt(Message.system("You are a language translator."));
+var response = client.chatCompletion(prompt, configWithTemplate).getContent();
+```
+
+Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OrchestrationService.java)
+
 ## Set model parameters
 
 Change your LLM configuration to add model parameters:

docs/release-notes/release-notes-0-to-14.md

@@ -1,3 +1,20 @@
+## 1.3.0 - February 13, 2025
+
+[All Release Changes](https://github.com/SAP/ai-sdk-java/releases/tag/rel%2F1.3.0)
+
+### 🔧 Compatibility Notes
+
+- `Message.content()` returns a `ContentItem` now instead of a `String`. Use `((TextItem) Message.content().items().get(0)).text()` if the corresponding `ContentItem` is a `TextItem` and the string representation is needed.
+
+### ✨ New Functionality
+
+- Upgrade to release 2502a of AI Core.
+- Orchestration:
+  - [Add `LlamaGuardFilter`](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#chat-completion-filter).
+  - [Convenient methods to create messages containing images and multiple text inputs](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#add-images-and-multiple-text-inputs-to-a-message)
+  - [Enable setting the response format](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#set-a-response-format)
+
+
 ## 1.2.0 - January 30, 2025
 
 [All Release Changes](https://github.com/SAP/ai-sdk-java/releases/tag/rel%2F1.2.0)
@@ -11,8 +28,8 @@
 ### ✨ New Functionality
 
 - New Orchestration features:
-  - [Spring AI integration](../guides/SPRING_AI_INTEGRATION.md)
-  - [Add Grounding configuration convenience](../guides/ORCHESTRATION_CHAT_COMPLETION.md#grounding)
+  - [Spring AI integration](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/SPRING_AI_INTEGRATION.md)
+  - [Add Grounding configuration convenience](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#grounding)
   - Images are now supported as input in newly introduced `MultiChatMessage`.
   - `MultiChatMessage` also allows for multiple content items (text or image) in one object.
   - Grounding input can be masked with `DPIConfig`.

docs/release-notes/release_notes.md

@@ -8,14 +8,11 @@
 
 ### 🔧 Compatibility Notes
 
-- `Message.content()` returns a `ContentItem` now instead of a `String`. Use `((TextItem) Message.content().items().get(0)).text()` if the corresponding `ContentItem` is a `TextItem` and the string representation is needed.
+- The constructors `UserMessage(MessageContent)` and `SystemMessage(MessageContent)` are removed. Use `Message.user(String)`, `Message.user(ImageItem)`, or `Message.system(String)` instead.
 
 ### ✨ New Functionality
 
-- Upgrade to release 2502a of AI Core.
-- Orchestration:
-  - [Add `LlamaGuardFilter`](../guides/ORCHESTRATION_CHAT_COMPLETION.md#chat-completion-filter).
-  - [Convenient methods to create messages containing images and multiple text inputs](../guides/ORCHESTRATION_CHAT_COMPLETION.md#add-images-and-multiple-text-inputs-to-a-message)
+-
 
 ### 📈 Improvements
 

foundation-models/openai/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <groupId>com.sap.ai.sdk</groupId>
     <artifactId>sdk-parent</artifactId>
-    <version>1.3.0-SNAPSHOT</version>
+    <version>1.4.0-SNAPSHOT</version>
     <relativePath>../../pom.xml</relativePath>
   </parent>
   <groupId>com.sap.ai.sdk.foundationmodels</groupId>