feat: [Orchestration] Allow for streaming configuration convenience API (#561)

* Initial

* Add test

* Add release note

* Add external link to javadoc

* Fix PMD

* Initial convenience class

* Initial convenience class

* Disable default stream

* Update release note

* JavaDoc fix

Author: newtork

docs/release_notes.md

@@ -45,6 +45,7 @@
 
 ### ✨ New Functionality
 
+- [Orchestration] For streaming, add convenience configuration for output-filter-overlap, chunk-size, and delimiters via `OrchestrationModuleConfig#withStreamConfig`.
 - [Orchestration] Added embedding generation support with new `OrchestrationClient#embed()` methods.
   - Added `OrchestrationEmbeddingModel` with `TEXT_EMBEDDING_3_SMALL`, `TEXT_EMBEDDING_3_LARGE`, `AMAZON_TITAN_EMBED_TEXT` and `NVIDIA_LLAMA_32_NV_EMBEDQA_1B` embedding models.
   - Introduced `OrchestrationEmbeddingRequest` for building requests fluently and `OrchestrationEmbeddingResponse#getEmbeddingVectors()` to retrieve embeddings.

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

@@ -38,8 +38,11 @@ static CompletionRequestConfiguration toCompletionPostRequest(
 
     val moduleConfigs = toModuleConfigs(configCopy);
 
+    val reqConfig =
+        OrchestrationConfig.create().modules(moduleConfigs).stream(config.getGlobalStreamOptions());
+
     return CompletionRequestConfiguration.create()
-        .config(OrchestrationConfig.create().modules(moduleConfigs))
+        .config(reqConfig)
         .placeholderValues(prompt.getTemplateParameters())
         .messagesHistory(messageHistory);
   }

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

@@ -220,7 +220,13 @@ public OrchestrationChatResponse executeRequestFromJsonModuleConfig(
   @Nonnull
   public Stream<OrchestrationChatCompletionDelta> streamChatCompletionDeltas(
       @Nonnull final CompletionRequestConfiguration request) throws OrchestrationClientException {
-    request.getConfig().setStream(GlobalStreamOptions.create().enabled(true).delimiters(null));
+    val config = request.getConfig();
+    val stream = config.getStream();
+    if (stream == null) {
+      config.setStream(GlobalStreamOptions.create().enabled(true).delimiters(null));
+    } else {
+      stream.enabled(true);
+    }
 
     return executor.stream(COMPLETION_ENDPOINT, request, customHeaders);
   }

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

@@ -2,6 +2,8 @@
 
 import com.google.common.annotations.Beta;
 import com.sap.ai.sdk.orchestration.model.FilteringModuleConfig;
+import com.sap.ai.sdk.orchestration.model.FilteringStreamOptions;
+import com.sap.ai.sdk.orchestration.model.GlobalStreamOptions;
 import com.sap.ai.sdk.orchestration.model.GroundingModuleConfig;
 import com.sap.ai.sdk.orchestration.model.InputFilteringConfig;
 import com.sap.ai.sdk.orchestration.model.LLMModelDetails;
@@ -18,6 +20,7 @@
 import javax.annotation.Nullable;
 import lombok.AccessLevel;
 import lombok.AllArgsConstructor;
+import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Value;
 import lombok.With;
@@ -101,6 +104,18 @@ public class OrchestrationModuleConfig {
 
   @Nullable SAPDocumentTranslationOutput outputTranslationConfig;
 
+  /** Configuration of optional streaming options for output filtering. */
+  @With(AccessLevel.NONE) // may be exposed to public in the future
+  @Getter(AccessLevel.PACKAGE)
+  @Nullable
+  FilteringStreamOptions outputFilteringStreamOptions;
+
+  /** Configuration of optional global streaming options, e.g. chunk-size. */
+  @With(AccessLevel.PRIVATE) // may be exposed to public in the future
+  @Getter(AccessLevel.PACKAGE)
+  @Nullable
+  GlobalStreamOptions globalStreamOptions;
+
   /**
    * Creates a new configuration with the given LLM configuration.
    *
@@ -116,6 +131,19 @@ public OrchestrationModuleConfig withLlmConfig(@Nonnull final OrchestrationAiMod
     return withLlmConfig(aiModel.createConfig());
   }
 
+  /**
+   * Creates a new configuration with the given stream configuration.
+   *
+   * @param config The stream configuration to use.
+   * @return A new configuration with the given stream configuration.
+   */
+  @Nonnull
+  public OrchestrationModuleConfig withStreamConfig(
+      @Nonnull final OrchestrationStreamConfig config) {
+    return this.withOutputFilteringStreamOptions(config.createFilteringStreamOptions())
+        .withGlobalStreamOptions(config.createGlobalStreamOptions());
+  }
+
   /**
    * Creates a new configuration with the given Data Masking configuration.
    *
@@ -204,7 +232,10 @@ public OrchestrationModuleConfig withOutputFiltering(
             .map(ContentFilter::createOutputFilterConfig)
             .toList();
 
-    final var outputFilter = OutputFilteringConfig.create().filters(filterConfigs);
+    final var outputFilter =
+        OutputFilteringConfig.create()
+            .filters(filterConfigs)
+            .streamOptions(outputFilteringStreamOptions);
 
     final var newFilteringConfig =
         FilteringModuleConfig.create()
@@ -214,6 +245,33 @@ public OrchestrationModuleConfig withOutputFiltering(
     return this.withFilteringConfig(newFilteringConfig);
   }
 
+  /**
+   * Creates a new configuration with the given output filtering stream options.
+   *
+   * @see <a
+   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/streaming">Orchestration
+   *     documentation on streaming.</a>
+   * @param outputFilteringStreamOptions The output filtering stream options to use.
+   * @return A new configuration with the given output filtering stream options.
+   */
+  @Nonnull
+  OrchestrationModuleConfig withOutputFilteringStreamOptions(
+      @Nullable final FilteringStreamOptions outputFilteringStreamOptions) {
+    if (filteringConfig != null && filteringConfig.getOutput() != null) {
+      filteringConfig.getOutput().setStreamOptions(outputFilteringStreamOptions);
+    }
+    return new OrchestrationModuleConfig(
+        this.llmConfig,
+        this.templateConfig,
+        this.maskingConfig,
+        this.filteringConfig,
+        this.groundingConfig,
+        this.inputTranslationConfig,
+        this.outputTranslationConfig,
+        outputFilteringStreamOptions,
+        this.globalStreamOptions);
+  }
+
   /**
    * Creates a new configuration with the given grounding configuration.
    *

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

@@ -0,0 +1,55 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.sap.ai.sdk.orchestration.model.FilteringStreamOptions;
+import com.sap.ai.sdk.orchestration.model.GlobalStreamOptions;
+import java.util.List;
+import java.util.Optional;
+import javax.annotation.Nullable;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Value;
+import lombok.With;
+import lombok.val;
+
+/**
+ * Configuration for orchestration streaming options.
+ *
+ * @since 1.12.0
+ */
+@Value
+@With
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+public class OrchestrationStreamConfig {
+  /**
+   * Number of characters that should be additionally sent to content filtering services from
+   * previous chunks as additional context.
+   */
+  @Nullable Integer filterOverlap;
+
+  /** Size of the chunks the response will be split into when streaming. */
+  @Nullable Integer chunkSize;
+
+  /** List of delimiters to use for chunking the response when streaming. */
+  @Nullable List<String> delimiters;
+
+  /** Default constructor for OrchestrationStreamConfig. */
+  public OrchestrationStreamConfig() {
+    this(null, null, null);
+  }
+
+  @Nullable
+  FilteringStreamOptions createFilteringStreamOptions() {
+    return filterOverlap == null ? null : FilteringStreamOptions.create().overlap(filterOverlap);
+  }
+
+  @Nullable
+  GlobalStreamOptions createGlobalStreamOptions() {
+    if (chunkSize == null && delimiters == null) {
+      return null;
+    }
+    val opts = GlobalStreamOptions.create();
+    Optional.ofNullable(chunkSize).ifPresent(opts::setChunkSize);
+    opts.setDelimiters(delimiters == null ? null : List.copyOf(delimiters));
+    return opts;
+  }
+}