Merge branch 'main' into chore/skip-generation-bydefault

Author: MatKuhr

.pipeline/checkstyle-suppressions.xml

@@ -6,8 +6,8 @@
 
 <suppressions>
   <!-- Suppress generated clients -->
-  <suppress files="/core/client/" checks=".*"/>
-  <suppress files="/orchestration/client/" checks=".*"/>
+  <suppress files="[/\\]core[/\\]client[/\\]" checks=".*"/>
+  <suppress files="[/\\]orchestration[/\\]client[/\\]" checks=".*"/>
   <!-- Suppress TODOs -->
   <suppress files="OpenAiChatCompletionParameters.java" checks="TodoComment" lines="95" />
   <suppress files="OpenAiChatMessage.java" checks="TodoComment" lines="255,271" />

README.md

@@ -3,7 +3,7 @@
 [![REUSE status](https://api.reuse.software/badge/git.fsfe.org/reuse/api)](https://api.reuse.software/info/git.fsfe.org/reuse/api)
 [![Fosstars security rating](https://github.com/SAP/cloud-sdk-java/blob/fosstars-report/fosstars_badge.svg)](https://github.com/SAP/cloud-sdk-java/blob/fosstars-report/fosstars_report.md)
 
-# SAP Cloud SDK for AI (for Java)
+# <img src="https://sap.github.io/cloud-sdk/img/logo.svg" alt="SAP Cloud SDK" width="30"/> SAP Cloud SDK for AI (for Java)
 
 > ⚠️ **This is a pre-alpha version of the AI SDK for Java. The APIs are subject to change.** ⚠️
 
@@ -12,7 +12,7 @@
 - [Introduction](#introduction)
 - [General Requirements](#general-requirements)
 - [Connecting to SAP AI Core](#connecting-to-sap-ai-core)
-    - [Option 1: Set Credentials as Environment Variable](#option-1-set-credentials-as-environment-variable)
+    - [Option 1: Set Credentials as Environment Variable](#option-1-set-ai-core-credentials)
     - [Option 2: Regular Service Binding in SAP BTP Cloud Foundry](#option-2-regular-service-binding-in-sap-btp-cloud-foundry)
     - [Option 3: Define and Use a Destination](#option-3-define-and-use-a-destination)
 - [Getting Started](#getting-started)
@@ -64,7 +64,7 @@ There are multiple ways to provide these credentials:
 
 | Option | Description                                                                                              |
 |--------|----------------------------------------------------------------------------------------------------------|
-| **1**  | Set an environment variable explicitly: `AICORE_SERVICE_KEY`                                             |
+| **1**  | Create an `.env` file containing an `AICORE_SERVICE_KEY={...}`                                           |
 | **2**  | Regular service binding in SAP BTP Cloud Foundry (results in `VCAP_SERVICES` environment variable entry) |
 | **3**  | Define and use a _Destination_ in the SAP BTP Destination Service                                        |
 
@@ -75,7 +75,7 @@ Additional methods (not recommended for production):
 - Leverage a "user-provided" service binding
 - Define and use a custom `ServiceBinding` or `ServiceBindingAccessor` in your application
 
-### Option 1: Set Credentials as Environment Variable
+### Option 1: Set AI Core Credentials
 
 <details>
 <summary>Click to view detailed steps</summary>
@@ -87,16 +87,33 @@ Additional methods (not recommended for production):
 - Navigate to **Instances and Subscriptions** -> **Instances** -> **AI Core**
 - Click **View Credentials** and copy the JSON content
 
-**2. Set Environment Variable:**
+**2. Create `.env` file:**
+
+- Create an `.env` file in the root directory of your application
+- Add an entry `AICORE_SERVICE_KEY='<content-of-service-key>'`
+
+<details>
+<summary>Set an environment variable instead of .env</summary>
+
+**2. Set an Environment Variable: (alternative)**
 
 - In your IDE or terminal, set the environment variable `AICORE_SERVICE_KEY` with the copied JSON content
 
-Example:
+  ℹ️ The environment variable has priority over the `.env` file.
+
+Example Linux/MacOS:
 
 ```shell
 export AICORE_SERVICE_KEY='{ "clientid": "...", "clientsecret": "...", "url": "...", "serviceurls": { "AI_API_URL": "..." } }'
 ```
 
+Example Windows:
+
+```shell
+$env:AICORE_SERVICE_KEY='{ "clientid": "...", "clientsecret": "...", "url": "...", "serviceurls": { "AI_API_URL": "..." } }'
+```
+
+</details>
 </details>
 
 ### Option 2: Regular Service Binding in SAP BTP Cloud Foundry
@@ -180,7 +197,7 @@ Before you begin, ensure you have:
 - Met the OpenAI Chat Completion module specific requirements
     - Refer to [Prerequisites for OpenAI Chat Completion](docs/guides/OPENAI_CHAT_COMPLETION.md#prerequisites)
 - Set up the AI Core credentials
-  using [(1) Environment Variable](#option-1-set-credentials-as-environment-variable)
+  using [(1) Environment variable or env-file](#option-1-set-ai-core-credentials)
   or [(2) Regular Service Binding](#option-2-regular-service-binding-in-sap-btp-cloud-foundry).
 - Deployed the OpenAI GPT-3.5 Turbo model in SAP AI Core.
     - Refer to [Deploying the OpenAI GPT-3.5 Turbo Model](docs/guides/OPENAI_CHAT_COMPLETION.md#usage)

core/pom.xml

@@ -98,6 +98,10 @@
       <groupId>io.vavr</groupId>
       <artifactId>vavr</artifactId>
     </dependency>
+    <dependency>
+      <groupId>io.github.cdimascio</groupId>
+      <artifactId>dotenv-java</artifactId>
+    </dependency>
     <!-- scope "runtime" -->
     <dependency>
       <groupId>com.sap.cloud.sdk.cloudplatform</groupId>

core/src/main/java/com/sap/ai/sdk/core/AiCoreService.java

@@ -15,6 +15,7 @@
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationAccessException;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationNotFoundException;
 import com.sap.cloud.sdk.services.openapi.apiclient.ApiClient;
+import io.github.cdimascio.dotenv.Dotenv;
 import java.util.NoSuchElementException;
 import java.util.function.BiFunction;
 import java.util.function.Function;
@@ -104,7 +105,7 @@ protected void destinationSetHeaders(@Nonnull final DefaultHttpDestination.Build
    */
   @Nonnull
   public AiCoreService withDestination(@Nonnull final Destination destination) {
-    baseDestinationHandler = (service) -> destination;
+    baseDestinationHandler = service -> destination;
     return this;
   }
 
@@ -160,7 +161,7 @@ public AiCoreDeployment forDeploymentByScenario(@Nonnull final String scenarioId
   @Nonnull
   protected Destination getBaseDestination()
       throws DestinationAccessException, DestinationNotFoundException {
-    val serviceKey = System.getenv("AICORE_SERVICE_KEY");
+    val serviceKey = Dotenv.configure().ignoreIfMissing().load().get("AICORE_SERVICE_KEY");
     return DestinationResolver.getDestination(serviceKey);
   }
 

core/src/main/java/com/sap/ai/sdk/core/DestinationResolver.java

@@ -22,11 +22,13 @@
 import javax.annotation.Nullable;
 import lombok.AccessLevel;
 import lombok.Getter;
+import lombok.NoArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import lombok.val;
 
 /** Utility class to resolve the destination pointing to the AI Core service. */
 @Slf4j
+@NoArgsConstructor(access = AccessLevel.PRIVATE) // utility class should not be instantiated
 class DestinationResolver {
   static final String AI_CLIENT_TYPE_KEY = "URL.headers.AI-Client-Type";
   static final String AI_CLIENT_TYPE_VALUE = "AI SDK Java";

core/src/test/java/com/sap/ai/sdk/core/AiCoreServiceTest.java

@@ -25,7 +25,7 @@
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 
-public class AiCoreServiceTest {
+class AiCoreServiceTest {
 
   // setup
   private static final Map<String, Object> URLS = Map.of("AI_API_URL", "https://srv");

core/src/test/java/com/sap/ai/sdk/core/client/ArtifactUnitTest.java

@@ -19,7 +19,7 @@
  * Test that queries are on the right URL, with the right headers. Also check that the received
  * response is parsed correctly in the generated client.
  */
-public class ArtifactUnitTest extends WireMockTestServer {
+class ArtifactUnitTest extends WireMockTestServer {
   @Test
   void getArtifacts() {
     wireMockServer.stubFor(

core/src/test/java/com/sap/ai/sdk/core/client/ConfigurationUnitTest.java

@@ -21,7 +21,7 @@
  * Test that queries are on the right URL, with the right headers. Also check that the received
  * response is parsed correctly in the generated client.
  */
-public class ConfigurationUnitTest extends WireMockTestServer {
+class ConfigurationUnitTest extends WireMockTestServer {
   @Test
   void getConfigurations() {
     wireMockServer.stubFor(

core/src/test/java/com/sap/ai/sdk/core/client/DeploymentUnitTest.java

@@ -32,7 +32,7 @@
  * Test that queries are on the right URL, with the right headers. Also check that the received
  * response is parsed correctly in the generated client.
  */
-public class DeploymentUnitTest extends WireMockTestServer {
+class DeploymentUnitTest extends WireMockTestServer {
   @Test
   void getDeployments() {
     wireMockServer.stubFor(
@@ -48,32 +48,43 @@ void getDeployments() {
                           "count": 1,
                           "resources": [
                             {
+                              "id": "d889e3a61050c085",
+                              "deploymentUrl": "https://api.ai.intprod-eu12.eu-central-1.aws.ml.hana.ondemand.com/v2/inference/deployments/d889e3a61050c085",
                               "configurationId": "7652a231-ba9b-4fcc-b473-2c355cb21b61",
                               "configurationName": "gpt-4-32k",
-                              "createdAt": "2024-04-17T15:19:53Z",
-                              "deploymentUrl": "https://api.ai.intprod-eu12.eu-central-1.aws.ml.hana.ondemand.com/v2/inference/deployments/d19b998f347341aa",
+                              "executableId": null,
+                              "scenarioId": "foundation-models",
+                              "status": "RUNNING",
+                              "statusMessage": null,
+                              "targetStatus": "RUNNING",
+                              "lastOperation": "CREATE",
+                              "latestRunningConfigurationId": "7652a231-ba9b-4fcc-b473-2c355cb21b61",
+                              "ttl": null,
                               "details": {
+                                "scaling": {
+                                  "backendDetails": {},
+                                  "backend_details": {}
+                                },
                                 "resources": {
+                                  "backendDetails": {
+                                    "model": {
+                                      "name": "gpt-4-32k",
+                                      "version": "latest"
+                                    }
+                                  },
                                   "backend_details": {
                                     "model": {
                                       "name": "gpt-4-32k",
                                       "version": "latest"
                                     }
                                   }
-                                },
-                                "scaling": {
-                                  "backend_details": {}
                                 }
                               },
-                              "id": "d19b998f347341aa",
-                              "lastOperation": "CREATE",
-                              "latestRunningConfigurationId": "7652a231-ba9b-4fcc-b473-2c355cb21b61",
-                              "modifiedAt": "2024-05-07T13:05:45Z",
-                              "scenarioId": "foundation-models",
-                              "startTime": "2024-04-17T15:21:15Z",
-                              "status": "RUNNING",
-                              "submissionTime": "2024-04-17T15:20:11Z",
-                              "targetStatus": "RUNNING"
+                              "createdAt": "2024-09-20T11:31:24Z",
+                              "modifiedAt": "2024-10-30T13:36:38Z",
+                              "submissionTime": "2024-09-20T11:31:38Z",
+                              "startTime": "2024-09-20T11:32:42Z",
+                              "completionTime": null
                             }
                           ]
                         }
@@ -89,24 +100,22 @@ void getDeployments() {
 
     assertThat(deployment.getConfigurationId()).isEqualTo("7652a231-ba9b-4fcc-b473-2c355cb21b61");
     assertThat(deployment.getConfigurationName()).isEqualTo("gpt-4-32k");
-    assertThat(deployment.getCreatedAt()).isEqualTo("2024-04-17T15:19:53Z");
+    assertThat(deployment.getCreatedAt()).isEqualTo("2024-09-20T11:31:24Z");
     assertThat(deployment.getDeploymentUrl())
         .isEqualTo(
-            "https://api.ai.intprod-eu12.eu-central-1.aws.ml.hana.ondemand.com/v2/inference/deployments/d19b998f347341aa");
+            "https://api.ai.intprod-eu12.eu-central-1.aws.ml.hana.ondemand.com/v2/inference/deployments/d889e3a61050c085");
     // Response contains key "backend_details" while spec (mistakenly) defines key "backendDetails".
     val expected = Map.of("model", Map.of("name", "gpt-4-32k", "version", "latest"));
-    assertThat(deployment.getDetails().getResources().getCustomField("backend_details"))
-        .isEqualTo(expected);
-    assertThat(deployment.getDetails().getScaling().getCustomFieldNames())
-        .contains("backend_details");
-    assertThat(deployment.getId()).isEqualTo("d19b998f347341aa");
+    assertThat(deployment.getDetails().getResources().getBackendDetails()).isEqualTo(expected);
+    assertThat(deployment.getDetails().getScaling().getBackendDetails()).isEqualTo(Map.of());
+    assertThat(deployment.getId()).isEqualTo("d889e3a61050c085");
     assertThat(deployment.getLastOperation()).isEqualTo(AiDeployment.LastOperationEnum.CREATE);
     assertThat(deployment.getLatestRunningConfigurationId())
         .isEqualTo("7652a231-ba9b-4fcc-b473-2c355cb21b61");
-    assertThat(deployment.getModifiedAt()).isEqualTo("2024-05-07T13:05:45Z");
-    assertThat(deployment.getStartTime()).isEqualTo("2024-04-17T15:21:15Z");
+    assertThat(deployment.getModifiedAt()).isEqualTo("2024-10-30T13:36:38Z");
+    assertThat(deployment.getStartTime()).isEqualTo("2024-09-20T11:32:42Z");
     assertThat(deployment.getStatus()).isEqualTo(AiDeploymentStatus.RUNNING);
-    assertThat(deployment.getSubmissionTime()).isEqualTo("2024-04-17T15:20:11Z");
+    assertThat(deployment.getSubmissionTime()).isEqualTo("2024-09-20T11:31:38Z");
     assertThat(deployment.getTargetStatus()).isEqualTo(AiDeployment.TargetStatusEnum.RUNNING);
   }
 
@@ -234,10 +243,12 @@ void getDeploymentById() {
                            "deploymentUrl": "https://api.ai.intprod-eu12.eu-central-1.aws.ml.hana.ondemand.com/v2/inference/deployments/db1d64d9f06be467",
                            "details": {
                              "resources": {
-                               "backend_details": {}
+                               "backend_details": {},
+                               "backendDetails": {}
                              },
                              "scaling": {
-                               "backend_details": {}
+                               "backend_details": {},
+                               "backendDetails": {}
                              }
                            },
                            "id": "db1d64d9f06be467",
@@ -261,11 +272,8 @@ void getDeploymentById() {
     assertThat(deployment.getDeploymentUrl())
         .isEqualTo(
             "https://api.ai.intprod-eu12.eu-central-1.aws.ml.hana.ondemand.com/v2/inference/deployments/db1d64d9f06be467");
-    // Response contains key "backend_details" while spec (mistakenly) defines key "backendDetails".
-    assertThat(deployment.getDetails().getResources().getCustomFieldNames())
-        .contains("backend_details");
-    assertThat(deployment.getDetails().getScaling().getCustomFieldNames())
-        .contains("backend_details");
+    assertThat(deployment.getDetails().getResources().getBackendDetails()).isNotNull();
+    assertThat(deployment.getDetails().getScaling().getBackendDetails()).isNotNull();
     assertThat(deployment.getId()).isEqualTo("db1d64d9f06be467");
     assertThat(deployment.getLastOperation())
         .isEqualTo(AiDeploymentResponseWithDetails.LastOperationEnum.CREATE);

core/src/test/java/com/sap/ai/sdk/core/client/ExecutionUnitTest.java

@@ -31,7 +31,7 @@
  * Test that queries are on the right URL, with the right headers. Also check that the received
  * response is parsed correctly in the generated client.
  */
-public class ExecutionUnitTest extends WireMockTestServer {
+class ExecutionUnitTest extends WireMockTestServer {
   @Test
   void getExecutions() {
     wireMockServer.stubFor(
@@ -100,7 +100,7 @@ void getExecutions() {
     val aiArtifact = execution.getOutputArtifacts().get(0);
 
     assertThat(aiArtifact.getCreatedAt()).isEqualTo("2023-08-05T14:10:05Z");
-    assertThat(aiArtifact.getDescription()).isEqualTo("");
+    assertThat(aiArtifact.getDescription()).isEmpty();
     assertThat(aiArtifact.getExecutionId()).isEqualTo("eab289226fe981da");
     assertThat(aiArtifact.getId()).isEqualTo("be0d728f-1cb2-4ff4-97ad-45c54ac592f6");
     assertThat(aiArtifact.getKind()).isEqualTo(AiArtifact.KindEnum.MODEL);
@@ -211,7 +211,7 @@ void getExecutionById() {
     val aiArtifact = execution.getOutputArtifacts().get(0);
 
     assertThat(aiArtifact.getCreatedAt()).isEqualTo("2024-09-09T19:10:48Z");
-    assertThat(aiArtifact.getDescription()).isEqualTo("");
+    assertThat(aiArtifact.getDescription()).isEmpty();
     assertThat(aiArtifact.getExecutionId()).isEqualTo("e529e8bd58740bc9");
     assertThat(aiArtifact.getId()).isEqualTo("c4792df8-da67-44fe-ad99-b5ea74bbb248");
     assertThat(aiArtifact.getKind()).isEqualTo(AiArtifact.KindEnum.MODEL);