javadoc, release notes, etc

Author: Jonas-Isr

docs/release_notes.md

@@ -25,6 +25,8 @@
 - [Orchestration] Deprecated `OrchestrationAiModel.IBM_GRANITE_13B_CHAT` with no replacement.
 - [OpenAI] [Introduced SpringAI integration with our OpenAI client.](https://sap.github.io/ai-sdk/docs/java/spring-ai/openai)
   - Added `OpenAiChatModel`
+- [Orchestration] [Added convenience to add custom headers to individual orchestration calls.](add link here)
+- [OpenAI] [Added convenience to add custom headers to individual LLM calls.](add link here)
 
 ### 📈 Improvements
 

foundation-models/openai/src/main/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiClient.java

@@ -139,9 +139,7 @@ public OpenAiClient withSystemPrompt(@Nonnull final String systemPrompt) {
   @Nonnull
   public OpenAiClient withHeader(@Nonnull final Header customHeader) {
     final var newDestination =
-        DefaultHttpDestination.fromDestination(this.destination)
-            .header(customHeader)
-            .build();
+        DefaultHttpDestination.fromDestination(this.destination).header(customHeader).build();
     return new OpenAiClient(newDestination);
   }
 

foundation-models/openai/src/test/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiClientTest.java

@@ -16,14 +16,13 @@
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiChatCompletionTool;
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiContentFilterPromptResults;
 import com.sap.ai.sdk.foundationmodels.openai.model.OpenAiEmbeddingParameters;
+import com.sap.cloud.sdk.cloudplatform.connectivity.Header;
 import java.io.IOException;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.Callable;
 import java.util.stream.Stream;
 import javax.annotation.Nonnull;
-
-import com.sap.cloud.sdk.cloudplatform.connectivity.Header;
 import lombok.SneakyThrows;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
@@ -487,14 +486,20 @@ void chatCompletionTool() {
   @Test
   void testCustomHeaders() {
     stubForChatCompletion();
-    final var request = new OpenAiChatCompletionRequest("Hello World! Why is this phrase so famous?");
+    final var request =
+        new OpenAiChatCompletionRequest("Hello World! Why is this phrase so famous?");
 
     var customHeader = new Header("foo", "bar");
-    final var result = client.withHeader("footoo", "barzar").withHeader(customHeader).chatCompletion(request);
+    final var result =
+        client.withHeader("footoo", "barzar").withHeader(customHeader).chatCompletion(request);
     assertThat(result).isNotNull();
 
     var newCustomHeader = new Header("foo", "baz");
-    var streamResult = client.withHeader("footoo", "barz").withHeader(newCustomHeader).streamChatCompletion("Hello World! Why is this phrase so famous?");
+    var streamResult =
+        client
+            .withHeader("footoo", "barz")
+            .withHeader(newCustomHeader)
+            .streamChatCompletion("Hello World! Why is this phrase so famous?");
     assertThat(streamResult).isNotNull();
 
     verify(

orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationClient.java

@@ -18,15 +18,13 @@
 import com.sap.cloud.sdk.cloudplatform.connectivity.Header;
 import com.sap.cloud.sdk.cloudplatform.connectivity.HttpDestination;
 import io.vavr.control.Try;
-
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Supplier;
 import java.util.stream.Stream;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
-
 import lombok.extern.slf4j.Slf4j;
 import lombok.val;
 
@@ -68,7 +66,9 @@ public OrchestrationClient(@Nonnull final HttpDestination destination) {
     this.executor = new OrchestrationHttpExecutor(() -> destination);
   }
 
-  private OrchestrationClient(@Nonnull OrchestrationHttpExecutor executor, @Nullable List<Header> customHeaders) {
+  private OrchestrationClient(
+      @Nonnull final OrchestrationHttpExecutor executor,
+      @Nullable final List<Header> customHeaders) {
     this.executor = executor;
     if (customHeaders != null) {
       this.customHeaders.addAll(customHeaders);
@@ -169,7 +169,8 @@ private static Map<String, Object> getOutputFilteringChoices(
   @Nonnull
   public CompletionPostResponse executeRequest(@Nonnull final CompletionPostRequest request)
       throws OrchestrationClientException {
-    return executor.execute(COMPLETION_ENDPOINT, request, CompletionPostResponse.class, customHeaders);
+    return executor.execute(
+        COMPLETION_ENDPOINT, request, CompletionPostResponse.class, customHeaders);
   }
 
   /**
@@ -211,7 +212,8 @@ public OrchestrationChatResponse executeRequestFromJsonModuleConfig(
     requestJson.set("orchestration_config", moduleConfigJson);
 
     return new OrchestrationChatResponse(
-        executor.execute(COMPLETION_ENDPOINT, requestJson, CompletionPostResponse.class, customHeaders));
+        executor.execute(
+            COMPLETION_ENDPOINT, requestJson, CompletionPostResponse.class, customHeaders));
   }
 
   /**
@@ -244,16 +246,32 @@ EmbeddingsPostResponse embed(@Nonnull final EmbeddingsPostRequest request)
     return executor.execute("/v2/embeddings", request, EmbeddingsPostResponse.class, customHeaders);
   }
 
-  private OrchestrationClient addHeader(Header header) {
-    this.customHeaders.add(header);
-    return this;
-  }
-
-  public OrchestrationClient withHeader(String key, String value) {
+  /**
+   * Create a new orchestration client with a custom header added to every call made with this
+   * client
+   *
+   * @param key the key of the custom header to add
+   * @param value the value of the custom header to add
+   * @return a new client.
+   */
+  @Beta
+  @Nonnull
+  public OrchestrationClient withHeader(@Nonnull final String key, @Nonnull final String value) {
     return this.withHeader(new Header(key, value));
   }
 
-  public OrchestrationClient withHeader(Header header) {
-    return new OrchestrationClient(this.executor, this.customHeaders).addHeader(header);
+  /**
+   * Create a new orchestration client with a custom header added to every call made with this
+   * client
+   *
+   * @param customHeader the custom header to add
+   * @return a new client.
+   */
+  @Beta
+  @Nonnull
+  public OrchestrationClient withHeader(@Nonnull final Header customHeader) {
+    final var newClient = new OrchestrationClient(this.executor, this.customHeaders);
+    newClient.customHeaders.add(customHeader);
+    return newClient;
   }
 }

orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationHttpExecutor.java

@@ -71,7 +71,9 @@ <T> T execute(
 
   @Nonnull
   Stream<OrchestrationChatCompletionDelta> stream(
-      @Nonnull final String path, @Nonnull final Object payload, @Nonnull final List<Header> customHeaders) {
+      @Nonnull final String path,
+      @Nonnull final Object payload,
+      @Nonnull final List<Header> customHeaders) {
     try {
 
       val json = JACKSON.writeValueAsString(payload);
@@ -95,7 +97,10 @@ Stream<OrchestrationChatCompletionDelta> stream(
 
   @Nonnull
   private HttpClient getHttpClient(@Nonnull final List<Header> customHeaders) {
-    val destination = DefaultHttpDestination.fromDestination(destinationSupplier.get()).headers(customHeaders).build();
+    val destination =
+        DefaultHttpDestination.fromDestination(destinationSupplier.get())
+            .headers(customHeaders)
+            .build();
     log.debug("Using destination {} to connect to orchestration service", destination);
     return ApacheHttpClient5Accessor.getHttpClient(destination);
   }

orchestration/src/test/java/com/sap/ai/sdk/orchestration/OrchestrationUnitTest.java

@@ -78,6 +78,7 @@
 import com.sap.cloud.sdk.cloudplatform.connectivity.ApacheHttpClient5Accessor;
 import com.sap.cloud.sdk.cloudplatform.connectivity.ApacheHttpClient5Cache;
 import com.sap.cloud.sdk.cloudplatform.connectivity.DefaultHttpDestination;
+import com.sap.cloud.sdk.cloudplatform.connectivity.Header;
 import java.io.IOException;
 import java.io.InputStream;
 import java.math.BigDecimal;
@@ -89,8 +90,6 @@
 import java.util.function.Function;
 import java.util.stream.Stream;
 import javax.annotation.Nonnull;
-
-import com.sap.cloud.sdk.cloudplatform.connectivity.Header;
 import lombok.val;
 import org.apache.hc.client5.http.classic.HttpClient;
 import org.apache.hc.core5.http.ContentType;
@@ -181,11 +180,19 @@ void testCustomHeaders() {
                     .withHeader("Content-Type", "application/json")));
 
     var customHeader = new Header("foo", "bar");
-    final var result = client.withHeader("footoo", "barzar").withHeader(customHeader).chatCompletion(prompt, config);
+    final var result =
+        client
+            .withHeader("footoo", "barzar")
+            .withHeader(customHeader)
+            .chatCompletion(prompt, config);
     assertThat(result).isNotNull();
 
     var newCustomHeader = new Header("foo", "baz");
-    var streamResult = client.withHeader("footoo", "barz").withHeader(newCustomHeader).streamChatCompletion(prompt, config);
+    var streamResult =
+        client
+            .withHeader("footoo", "barz")
+            .withHeader(newCustomHeader)
+            .streamChatCompletion(prompt, config);
     assertThat(streamResult).isNotNull();
 
     verify(