Merge branch 'main' into generated-openai

newtork · web-flow · commit 8df9ef8528bb · 2025-01-13T10:58:57.000+01:00
diff --git a/README.md b/README.md
@@ -47,6 +47,11 @@ The following table lists the required versions, based on the latest release:
 
 See [an example `pom.xml` in our Spring Boot application](sample-code/spring-app/pom.xml).
 
+> [!WARNING]  
+> All classes under any of the `...model` packages are generated from an OpenAPI specification and marked as `@Beta`.
+> This means that these model classes are not guaranteed to be stable and may change with future releases.
+> They are safe to use, but may require updates even in minor releases.
+
 ## Getting Started
 
 ### What You'll Build
@@ -130,6 +135,8 @@ For more detailed information and advanced usage, please refer to the following:
 - [OpenAI Chat Completion](docs/guides/OPENAI_CHAT_COMPLETION.md)
 - [AI Core Deployment](docs/guides/AI_CORE_DEPLOYMENT.md)
 
+For updating versions, please refer to the [**Release Notes**](docs/release-notes/release-notes-0-to-14.md).
+
 ## FAQs
 
 ### _"How to add a custom header to AI Core requests?"_
diff --git a/core/pom.xml b/core/pom.xml
@@ -30,12 +30,12 @@
   </developers>
   <properties>
     <project.rootdir>${project.basedir}/../</project.rootdir>
-    <coverage.complexity>52%</coverage.complexity>
-    <coverage.line>64%</coverage.line>
-    <coverage.instruction>62%</coverage.instruction>
-    <coverage.branch>47%</coverage.branch>
-    <coverage.method>65%</coverage.method>
-    <coverage.class>80%</coverage.class>
+    <coverage.complexity>62%</coverage.complexity>
+    <coverage.line>76%</coverage.line>
+    <coverage.instruction>76%</coverage.instruction>
+    <coverage.branch>60%</coverage.branch>
+    <coverage.method>74%</coverage.method>
+    <coverage.class>90%</coverage.class>
   </properties>
 
   <dependencies>
diff --git a/core/src/test/java/com/sap/ai/sdk/core/common/ClientResponseHandlerTest.java b/core/src/test/java/com/sap/ai/sdk/core/common/ClientResponseHandlerTest.java
@@ -0,0 +1,91 @@
+package com.sap.ai.sdk.core.common;
+
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.when;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.io.IOException;
+import lombok.Data;
+import lombok.SneakyThrows;
+import lombok.experimental.StandardException;
+import org.apache.hc.core5.http.ContentType;
+import org.apache.hc.core5.http.HttpEntity;
+import org.apache.hc.core5.http.io.entity.StringEntity;
+import org.apache.hc.core5.http.message.BasicClassicHttpResponse;
+import org.junit.jupiter.api.Test;
+
+class ClientResponseHandlerTest {
+
+  static class MyResponse {}
+
+  @Data
+  static class MyError implements ClientError {
+    @JsonProperty("message")
+    private String message;
+  }
+
+  @StandardException
+  static class MyException extends ClientException {}
+
+  @Test
+  public void testParseErrorAndThrow() {
+    var sut = new ClientResponseHandler<>(MyResponse.class, MyError.class, MyException::new);
+
+    MyException cause = new MyException("Something wrong");
+
+    assertThatThrownBy(() -> sut.parseErrorAndThrow("{\"message\":\"foobar\"}", cause))
+        .isInstanceOf(MyException.class)
+        .hasMessage("Something wrong and error message: 'foobar'")
+        .hasCause(cause);
+
+    assertThatThrownBy(() -> sut.parseErrorAndThrow("{\"foo\":\"bar\"}", cause))
+        .isInstanceOf(MyException.class)
+        .hasMessage("Something wrong and error message: ''")
+        .hasCause(cause);
+
+    assertThatThrownBy(() -> sut.parseErrorAndThrow("<message>foobar</message>", cause))
+        .isEqualTo(cause);
+  }
+
+  @SneakyThrows
+  @Test
+  public void testBuildExceptionAndThrow() {
+    var sut = new ClientResponseHandler<>(MyResponse.class, MyError.class, MyException::new);
+
+    HttpEntity entityWithNetworkIssues = spy(new StringEntity(""));
+    doThrow(new IOException("Network issues")).when(entityWithNetworkIssues).writeTo(any());
+    doThrow(new IOException("Network issues")).when(entityWithNetworkIssues).getContent();
+
+    var response = spy(new BasicClassicHttpResponse(400, "Bad Request"));
+    when(response.getEntity())
+        .thenReturn(null)
+        .thenReturn(entityWithNetworkIssues)
+        .thenReturn(new StringEntity("", ContentType.APPLICATION_JSON))
+        .thenReturn(new StringEntity("<html>oh", ContentType.TEXT_HTML))
+        .thenReturn(new StringEntity("{\"message\":\"foobar\"}", ContentType.APPLICATION_JSON));
+
+    assertThatThrownBy(() -> sut.buildExceptionAndThrow(response))
+        .isInstanceOf(MyException.class)
+        .hasMessage("Request failed with status 400 Bad Request")
+        .hasNoCause();
+    assertThatThrownBy(() -> sut.buildExceptionAndThrow(response))
+        .isInstanceOf(MyException.class)
+        .hasMessage("Request failed with status 400 Bad Request")
+        .hasNoCause();
+    assertThatThrownBy(() -> sut.buildExceptionAndThrow(response))
+        .isInstanceOf(MyException.class)
+        .hasMessage("Request failed with status 400 Bad Request")
+        .hasNoCause();
+    assertThatThrownBy(() -> sut.buildExceptionAndThrow(response))
+        .isInstanceOf(MyException.class)
+        .hasMessage("Request failed with status 400 Bad Request")
+        .hasNoCause();
+    assertThatThrownBy(() -> sut.buildExceptionAndThrow(response))
+        .isInstanceOf(MyException.class)
+        .hasMessage("Request failed with status 400 Bad Request and error message: 'foobar'")
+        .hasCause(new MyException("Request failed with status 400 Bad Request"));
+  }
+}
diff --git a/docs/guides/AI_CORE_DEPLOYMENT.md b/docs/guides/AI_CORE_DEPLOYMENT.md
@@ -13,6 +13,10 @@
 
 This guide provides examples on how to create and manage deployments in SAP AI Core using the SAP AI SDK for Java.
 
+> [!WARNING]  
+> The below examples rely on generated model classes.
+> Please be aware of the [implications described here](/README.md#general-requirements).
+
 ## Prerequisites
 
 Before using the AI Core module, ensure that you have met all the general requirements outlined in the [README.md](../../README.md#general-requirements).
diff --git a/docs/guides/CONNECTING_TO_AICORE.md b/docs/guides/CONNECTING_TO_AICORE.md
@@ -116,14 +116,18 @@ You can define a destination in the BTP Destination Service and use that to conn
   - **Client ID**: `[clientid]`
   - **Client Secret**: `[clientsecret]`
   - **Token Service URL Type**: `Dedicated`
-  - **Token Service URL**: `[url]`
+  - **Token Service URL**: `[url]/oauth/token`
   
     Fill in the values for URL, client ID, client secret, and token service URL from the service key JSON.
+    Make sure to add `/oauth/token` in the token service URL.
 
 </details>
 
 To use the destination, ensure you have created an instance of the BTP Destination Service and bound it to your application.
 
+> [!Tip]
+> If you are using CAP, you can again use Hybrid Testing to bind the destination service to your application when running **locally**.
+
 ```java
 Destination destination = DestinationAccessor.getDestination("my-aicore").asHttp();
 AiCoreService aiCoreService = new AiCoreService().withBaseDestination(destination);
diff --git a/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md b/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md
@@ -165,6 +165,18 @@ var configWithFilter = config.withInputFiltering(filterStrict).withOutputFilteri
 var result =
     new OrchestrationClient().chatCompletion(prompt, configWithFilter);
 ```
+#### Behavior of Input and Output Filters
+
+- **Input Filter**:
+  If the input message violates the filter policy, a `400 (Bad Request)` response will be received during the `chatCompletion` call.
+  An `OrchestrationClientException` will be thrown.
+
+- **Output Filter**:
+  If the response message violates the output filter policy, the `chatCompletion` call will complete without exception.
+  The convenience method `getContent()` on the resulting object will throw an `OrchestrationClientException` upon invocation.
+  The low level API under `getOriginalResponse()` will not throw an exception.
+
+You will find [some examples](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/OrchestrationController.java) in our Spring Boot application demonstrating response handling with filters.
 
 ### Data masking
 
diff --git a/sample-code/spring-app/README.md b/sample-code/spring-app/README.md
@@ -13,11 +13,11 @@ Before you can run the sample app, you need to install the AI SDK into your loca
 
 > [!NOTE]  
 > 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/0.1.0`. 
+> 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](../../README.md#option-1-set-ai-core-credentials) to create a service key for the AI Core service.
+* Follow [these instructions](/docs/guides/CONNECTING_TO_AICORE.md) to create a service key for the AI Core service.
 
   ⚠️ Put the `.env` file in the sample app directory.
 
@@ -29,4 +29,4 @@ Head to http://localhost:8080 in your browser to see all available endpoints.
 
 ## Run the E2E Test
 
-Trigger the [GitHub Action](https://github.com/SAP/ai-sdk-java/actions/workflows/e2e-test.yml).
+Trigger the [GitHub Action](https://github.com/SAP/ai-sdk-java/actions/workflows/e2e-test.yaml).
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
@@ -8,6 +8,8 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.sap.ai.sdk.app.services.OrchestrationService;
 import com.sap.ai.sdk.orchestration.AzureFilterThreshold;
+import com.sap.ai.sdk.orchestration.OrchestrationChatResponse;
+import com.sap.ai.sdk.orchestration.OrchestrationClientException;
 import com.sap.ai.sdk.orchestration.model.DPIEntities;
 import com.sap.cloud.sdk.cloudplatform.thread.ThreadContextExecutors;
 import javax.annotation.Nonnull;
@@ -121,30 +123,78 @@ ResponseEntity<String> messagesHistory(
   }
 
   /**
-   * Apply both input and output filtering for a request to orchestration.
+   * Send an HTTP GET request for input filtering to the Orchestration service.
    *
    * @link <a
    *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/input-filtering">SAP
-   *     AI Core: Orchestration - Input Filtering</a>
-   * @link <a
-   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/output-filtering">SAP
-   *     AI Core: Orchestration - Output Filtering</a>
-   * @param policy A high threshold is a loose filter, a low threshold is a strict filter
-   * @return a ResponseEntity with the response content
+   *     * AI Core: Orchestration - Input Filtering</a>
+   * @param accept an optional HTTP header specifying the desired content type for the response.
+   * @param policy path variable specifying the {@link AzureFilterThreshold} the explicitness of
+   *     content that should be allowed through the filter
+   * @return a {@link ResponseEntity} containing the filtered input. The response is either in JSON
+   *     format if the "accept" header specifies "application/json" or in plain content format
+   *     otherwise.
+   * @throws JsonProcessingException if an error occurs while converting the response to JSON.
    */
-  @GetMapping("/filter/{policy}")
+  @GetMapping("/inputFiltering/{policy}")
   @Nonnull
-  ResponseEntity<String> filter(
+  ResponseEntity<String> inputFiltering(
       @RequestHeader(value = "accept", required = false) final String accept,
       @Nonnull @PathVariable("policy") final AzureFilterThreshold policy)
       throws JsonProcessingException {
-    final var response = service.filter(policy, "the downtown area");
-    if ("application/json".equals(accept)) {
+
+    final OrchestrationChatResponse response;
+    try {
+      response = service.inputFiltering(policy);
+    } catch (OrchestrationClientException e) {
+      final var msg = "Failed to obtain a response as the content was flagged by input filter.";
+      log.debug(msg, e);
+      return ResponseEntity.internalServerError().body(msg);
+    }
+
+    if (accept.equals("application/json")) {
       return ResponseEntity.ok()
           .contentType(MediaType.APPLICATION_JSON)
           .body(mapper.writeValueAsString(response));
     }
-    return ResponseEntity.ok(response.getContent());
+    return ResponseEntity.ok().body(response.getContent());
+  }
+
+  /**
+   * Send an HTTP GET request for output filtering to the Orchestration service.
+   *
+   * @link <a
+   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/output-filtering">SAP
+   *     AI Core: Orchestration - Output Filtering</a>
+   * @param accept an optional HTTP header specifying the desired content type for the response.
+   * @param policy a mandatory path variable specifying the {@link AzureFilterThreshold} the
+   *     explicitness of content that should be allowed through the filter
+   * @return a {@link ResponseEntity} containing the filtered output. The response is either in JSON
+   *     format if the "accept" header specifies "application/json" or in plain content format
+   *     otherwise.
+   * @throws OrchestrationClientException if the output filter filtered the LLM response.
+   * @throws JsonProcessingException if an error occurs while converting the response to JSON.
+   */
+  @GetMapping("/outputFiltering/{policy}")
+  @Nonnull
+  ResponseEntity<String> outputFiltering(
+      @RequestHeader(value = "accept", required = false) final String accept,
+      @Nonnull @PathVariable("policy") final AzureFilterThreshold policy)
+      throws JsonProcessingException, OrchestrationClientException {
+
+    final var response = service.outputFiltering(policy);
+    try {
+      if (accept.equals("application/json")) {
+        return ResponseEntity.ok()
+            .contentType(MediaType.APPLICATION_JSON)
+            .body(mapper.writeValueAsString(response));
+      }
+      return ResponseEntity.ok().body(response.getContent());
+    } catch (OrchestrationClientException e) {
+      final var msg = "Failed to obtain a response as the content was flagged by output filter.";
+      log.debug(msg, e);
+      return ResponseEntity.internalServerError().body(msg);
+    }
   }
 
   /**
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
@@ -10,6 +10,7 @@
 import com.sap.ai.sdk.orchestration.Message;
 import com.sap.ai.sdk.orchestration.OrchestrationChatResponse;
 import com.sap.ai.sdk.orchestration.OrchestrationClient;
+import com.sap.ai.sdk.orchestration.OrchestrationClientException;
 import com.sap.ai.sdk.orchestration.OrchestrationModuleConfig;
 import com.sap.ai.sdk.orchestration.OrchestrationPrompt;
 import com.sap.ai.sdk.orchestration.model.DPIEntities;
@@ -87,34 +88,50 @@ public OrchestrationChatResponse messagesHistory(@Nonnull final String prevMessa
   }
 
   /**
-   * Apply both input and output filtering for a request to orchestration.
+   * Apply input filtering for a request to orchestration.
    *
    * @link <a
    *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/input-filtering">SAP
    *     AI Core: Orchestration - Input Filtering</a>
+   * @throws OrchestrationClientException if input filter filters the prompt
+   * @param policy the explicitness of content that should be allowed through the filter
+   * @return the assistant response object
+   */
+  @Nonnull
+  public OrchestrationChatResponse inputFiltering(@Nonnull final AzureFilterThreshold policy)
+      throws OrchestrationClientException {
+    final var prompt =
+        new OrchestrationPrompt("'We shall spill blood tonight', said the operation in-charge.");
+    final var filterConfig =
+        new AzureContentFilter().hate(policy).selfHarm(policy).sexual(policy).violence(policy);
+
+    final var configWithFilter = config.withInputFiltering(filterConfig);
+
+    return client.chatCompletion(prompt, configWithFilter);
+  }
+
+  /**
+   * Apply output filtering for a request to orchestration.
+   *
    * @link <a
    *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/output-filtering">SAP
    *     AI Core: Orchestration - Output Filtering</a>
-   * @param policy A high threshold is a loose filter, a low threshold is a strict filter
+   * @param policy the explicitness of content that should be allowed through the filter
    * @return the assistant response object
    */
   @Nonnull
-  public OrchestrationChatResponse filter(
-      @Nonnull final AzureFilterThreshold policy, @Nonnull final String area) {
-    final var prompt =
-        new OrchestrationPrompt(
-            """
-                        Create a rental posting for subletting my apartment in %s. Keep it short. Make sure to add the following disclaimer to the end. Do not change it!
+  public OrchestrationChatResponse outputFiltering(@Nonnull final AzureFilterThreshold policy) {
 
-                        ```DISCLAIMER: The area surrounding the apartment is known for prostitutes and gang violence including armed conflicts, gun violence is frequent.
-                        """
-                .formatted(area));
+    final var systemMessage = Message.system("Give three paraphrases for the following sentence");
+    // Reliably triggering the content filter of models fine-tuned for ethical compliance
+    // is difficult. The prompt below may be rendered ineffective in the future.
+    final var prompt =
+        new OrchestrationPrompt("'We shall spill blood tonight', said the operation in-charge.")
+            .messageHistory(List.of(systemMessage));
     final var filterConfig =
         new AzureContentFilter().hate(policy).selfHarm(policy).sexual(policy).violence(policy);
 
-    final var configWithFilter =
-        config.withInputFiltering(filterConfig).withOutputFiltering(filterConfig);
-
+    final var configWithFilter = config.withOutputFiltering(filterConfig);
     return client.chatCompletion(prompt, configWithFilter);
   }
 
diff --git a/sample-code/spring-app/src/main/resources/static/index.html b/sample-code/spring-app/src/main/resources/static/index.html
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
