chore: Orchestration spec update for config by reference (#596)

* generation

* apply fix

* add release note on breaking change

Author: Jonas-Isr

docs/release_notes.md

@@ -9,10 +9,14 @@
 ### 🔧 Compatibility Notes
 
 - Breaking change:
-  - two fields in `OrchestrationModuleConfig` changed:
+  - `CompletionPostRequest` is now an interface instead of a class. 
+    For all previous use-cases, it should be substitutable with the new class `CompletionRequestConfiguration`.
+    - `OrchestrationClient.toCompletionPostRequest()` now returns `CompletionRequestConfiguration`.
+    - `OrchestrationClient.streamChatCompletionDeltas()` takes `CompletionRequestConfiguration` as an input now.
+  - Two fields in `OrchestrationModuleConfig` changed:
     - `inputTranslationConfig` is now of type `SAPDocumentTranslationInput`
     - `outputTranslationConfig` is now of type `SAPDocumentTranslationOutput`
-  - when using `OrchestrationModuleConfig.withInputTranslationConfig()` and `OrchestrationModuleConfig.withOutputTranslationConfig()` consider the following diff:
+  - When using `OrchestrationModuleConfig.withInputTranslationConfig()` and `OrchestrationModuleConfig.withOutputTranslationConfig()` consider the following diff:
     ```diff
     var config = new OrchestrationModuleConfig("some prompt");
     config

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

@@ -1,7 +1,7 @@
 package com.sap.ai.sdk.orchestration;
 
 import com.sap.ai.sdk.orchestration.model.ChatMessage;
-import com.sap.ai.sdk.orchestration.model.CompletionPostRequest;
+import com.sap.ai.sdk.orchestration.model.CompletionRequestConfiguration;
 import com.sap.ai.sdk.orchestration.model.ModuleConfigs;
 import com.sap.ai.sdk.orchestration.model.OrchestrationConfig;
 import com.sap.ai.sdk.orchestration.model.PromptTemplatingModuleConfig;
@@ -21,7 +21,7 @@
 @NoArgsConstructor(access = AccessLevel.NONE)
 final class ConfigToRequestTransformer {
   @Nonnull
-  static CompletionPostRequest toCompletionPostRequest(
+  static CompletionRequestConfiguration toCompletionPostRequest(
       @Nonnull final OrchestrationPrompt prompt, @Nonnull final OrchestrationModuleConfig config) {
     val template = toTemplateModuleConfig(prompt, config.getTemplateConfig());
 
@@ -38,7 +38,7 @@ static CompletionPostRequest toCompletionPostRequest(
 
     val moduleConfigs = toModuleConfigs(configCopy);
 
-    return CompletionPostRequest.create()
+    return CompletionRequestConfiguration.create()
         .config(OrchestrationConfig.create().modules(moduleConfigs))
         .placeholderValues(prompt.getTemplateParameters())
         .messagesHistory(messageHistory);

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

@@ -10,6 +10,7 @@
 import com.sap.ai.sdk.core.AiCoreService;
 import com.sap.ai.sdk.orchestration.model.CompletionPostRequest;
 import com.sap.ai.sdk.orchestration.model.CompletionPostResponse;
+import com.sap.ai.sdk.orchestration.model.CompletionRequestConfiguration;
 import com.sap.ai.sdk.orchestration.model.EmbeddingsPostRequest;
 import com.sap.ai.sdk.orchestration.model.EmbeddingsPostResponse;
 import com.sap.ai.sdk.orchestration.model.GlobalStreamOptions;
@@ -76,7 +77,7 @@ public OrchestrationClient(@Nonnull final HttpDestination destination) {
    * @return The low-level request data object to send to orchestration.
    */
   @Nonnull
-  public static CompletionPostRequest toCompletionPostRequest(
+  public static CompletionRequestConfiguration toCompletionPostRequest(
       @Nonnull final OrchestrationPrompt prompt, @Nonnull final OrchestrationModuleConfig config) {
     return ConfigToRequestTransformer.toCompletionPostRequest(prompt, config);
   }
@@ -218,7 +219,7 @@ public OrchestrationChatResponse executeRequestFromJsonModuleConfig(
    */
   @Nonnull
   public Stream<OrchestrationChatCompletionDelta> streamChatCompletionDeltas(
-      @Nonnull final CompletionPostRequest request) throws OrchestrationClientException {
+      @Nonnull final CompletionRequestConfiguration request) throws OrchestrationClientException {
     request.getConfig().setStream(GlobalStreamOptions.create().enabled(true).delimiters(null));
 
     return executor.stream(COMPLETION_ENDPOINT, request, customHeaders);

orchestration/src/main/java/com/sap/ai/sdk/orchestration/model/CompletionPostRequest.java

@@ -11,291 +11,14 @@
 
 package com.sap.ai.sdk.orchestration.model;
 
-import com.fasterxml.jackson.annotation.JsonAnyGetter;
-import com.fasterxml.jackson.annotation.JsonAnySetter;
-import com.fasterxml.jackson.annotation.JsonIgnore;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.NoSuchElementException;
-import java.util.Objects;
-import java.util.Set;
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
 
 /** CompletionPostRequest */
-// CHECKSTYLE:OFF
-public class CompletionPostRequest
-// CHECKSTYLE:ON
-{
-  @JsonProperty("config")
-  private OrchestrationConfig config;
-
-  @JsonProperty("placeholder_values")
-  private Map<String, String> placeholderValues = new HashMap<>();
-
-  @JsonProperty("messages_history")
-  private List<ChatMessage> messagesHistory;
-
-  @JsonAnySetter @JsonAnyGetter
-  private final Map<String, Object> cloudSdkCustomFields = new LinkedHashMap<>();
-
-  /** Default constructor for CompletionPostRequest. */
-  protected CompletionPostRequest() {}
-
-  /**
-   * Set the config of this {@link CompletionPostRequest} instance and return the same instance.
-   *
-   * @param config The config of this {@link CompletionPostRequest}
-   * @return The same instance of this {@link CompletionPostRequest} class
-   */
-  @Nonnull
-  public CompletionPostRequest config(@Nonnull final OrchestrationConfig config) {
-    this.config = config;
-    return this;
-  }
-
-  /**
-   * Get config
-   *
-   * @return config The config of this {@link CompletionPostRequest} instance.
-   */
-  @Nonnull
-  public OrchestrationConfig getConfig() {
-    return config;
-  }
-
-  /**
-   * Set the config of this {@link CompletionPostRequest} instance.
-   *
-   * @param config The config of this {@link CompletionPostRequest}
-   */
-  public void setConfig(@Nonnull final OrchestrationConfig config) {
-    this.config = config;
-  }
-
-  /**
-   * Set the placeholderValues of this {@link CompletionPostRequest} instance and return the same
-   * instance.
-   *
-   * @param placeholderValues The placeholderValues of this {@link CompletionPostRequest}
-   * @return The same instance of this {@link CompletionPostRequest} class
-   */
-  @Nonnull
-  public CompletionPostRequest placeholderValues(
-      @Nullable final Map<String, String> placeholderValues) {
-    this.placeholderValues = placeholderValues;
-    return this;
-  }
-
-  /**
-   * Put one placeholderValues instance to this {@link CompletionPostRequest} instance.
-   *
-   * @param key The String key of this placeholderValues instance
-   * @param placeholderValuesItem The placeholderValues that should be added under the given key
-   * @return The same instance of type {@link CompletionPostRequest}
-   */
-  @Nonnull
-  public CompletionPostRequest putplaceholderValuesItem(
-      @Nonnull final String key, @Nonnull final String placeholderValuesItem) {
-    if (this.placeholderValues == null) {
-      this.placeholderValues = new HashMap<>();
-    }
-    this.placeholderValues.put(key, placeholderValuesItem);
-    return this;
-  }
-
-  /**
-   * Get placeholderValues
-   *
-   * @return placeholderValues The placeholderValues of this {@link CompletionPostRequest} instance.
-   */
-  @Nonnull
-  public Map<String, String> getPlaceholderValues() {
-    return placeholderValues;
-  }
-
-  /**
-   * Set the placeholderValues of this {@link CompletionPostRequest} instance.
-   *
-   * @param placeholderValues The placeholderValues of this {@link CompletionPostRequest}
-   */
-  public void setPlaceholderValues(@Nullable final Map<String, String> placeholderValues) {
-    this.placeholderValues = placeholderValues;
-  }
-
-  /**
-   * Set the messagesHistory of this {@link CompletionPostRequest} instance and return the same
-   * instance.
-   *
-   * @param messagesHistory History of chat messages. Can be used to provide system and assistant
-   *     messages to set the context of the conversation. Will be merged with the template message
-   * @return The same instance of this {@link CompletionPostRequest} class
-   */
-  @Nonnull
-  public CompletionPostRequest messagesHistory(@Nullable final List<ChatMessage> messagesHistory) {
-    this.messagesHistory = messagesHistory;
-    return this;
-  }
-
-  /**
-   * Add one messagesHistory instance to this {@link CompletionPostRequest}.
-   *
-   * @param messagesHistoryItem The messagesHistory that should be added
-   * @return The same instance of type {@link CompletionPostRequest}
-   */
-  @Nonnull
-  public CompletionPostRequest addMessagesHistoryItem(
-      @Nonnull final ChatMessage messagesHistoryItem) {
-    if (this.messagesHistory == null) {
-      this.messagesHistory = new ArrayList<>();
-    }
-    this.messagesHistory.add(messagesHistoryItem);
-    return this;
-  }
-
-  /**
-   * History of chat messages. Can be used to provide system and assistant messages to set the
-   * context of the conversation. Will be merged with the template message
-   *
-   * @return messagesHistory The messagesHistory of this {@link CompletionPostRequest} instance.
-   */
-  @Nonnull
-  public List<ChatMessage> getMessagesHistory() {
-    return messagesHistory;
-  }
-
-  /**
-   * Set the messagesHistory of this {@link CompletionPostRequest} instance.
-   *
-   * @param messagesHistory History of chat messages. Can be used to provide system and assistant
-   *     messages to set the context of the conversation. Will be merged with the template message
-   */
-  public void setMessagesHistory(@Nullable final List<ChatMessage> messagesHistory) {
-    this.messagesHistory = messagesHistory;
-  }
-
-  /**
-   * Get the names of the unrecognizable properties of the {@link CompletionPostRequest}.
-   *
-   * @return The set of properties names
-   */
-  @JsonIgnore
-  @Nonnull
-  public Set<String> getCustomFieldNames() {
-    return cloudSdkCustomFields.keySet();
-  }
-
-  /**
-   * Get the value of an unrecognizable property of this {@link CompletionPostRequest} instance.
-   *
-   * @deprecated Use {@link #toMap()} instead.
-   * @param name The name of the property
-   * @return The value of the property
-   * @throws NoSuchElementException If no property with the given name could be found.
-   */
-  @Nullable
-  @Deprecated
-  public Object getCustomField(@Nonnull final String name) throws NoSuchElementException {
-    if (!cloudSdkCustomFields.containsKey(name)) {
-      throw new NoSuchElementException(
-          "CompletionPostRequest has no field with name '" + name + "'.");
-    }
-    return cloudSdkCustomFields.get(name);
-  }
-
-  /**
-   * Get the value of all properties of this {@link CompletionPostRequest} instance including
-   * unrecognized properties.
-   *
-   * @return The map of all properties
-   */
-  @JsonIgnore
-  @Nonnull
-  public Map<String, Object> toMap() {
-    final Map<String, Object> declaredFields = new LinkedHashMap<>(cloudSdkCustomFields);
-    if (config != null) declaredFields.put("config", config);
-    if (placeholderValues != null) declaredFields.put("placeholderValues", placeholderValues);
-    if (messagesHistory != null) declaredFields.put("messagesHistory", messagesHistory);
-    return declaredFields;
-  }
-
-  /**
-   * Set an unrecognizable property of this {@link CompletionPostRequest} instance. If the map
-   * previously contained a mapping for the key, the old value is replaced by the specified value.
-   *
-   * @param customFieldName The name of the property
-   * @param customFieldValue The value of the property
-   */
-  @JsonIgnore
-  public void setCustomField(@Nonnull String customFieldName, @Nullable Object customFieldValue) {
-    cloudSdkCustomFields.put(customFieldName, customFieldValue);
-  }
-
-  @Override
-  public boolean equals(@Nullable final java.lang.Object o) {
-    if (this == o) {
-      return true;
-    }
-    if (o == null || getClass() != o.getClass()) {
-      return false;
-    }
-    final CompletionPostRequest completionPostRequest = (CompletionPostRequest) o;
-    return Objects.equals(this.cloudSdkCustomFields, completionPostRequest.cloudSdkCustomFields)
-        && Objects.equals(this.config, completionPostRequest.config)
-        && Objects.equals(this.placeholderValues, completionPostRequest.placeholderValues)
-        && Objects.equals(this.messagesHistory, completionPostRequest.messagesHistory);
-  }
-
-  @Override
-  public int hashCode() {
-    return Objects.hash(config, placeholderValues, messagesHistory, cloudSdkCustomFields);
-  }
-
-  @Override
-  @Nonnull
-  public String toString() {
-    final StringBuilder sb = new StringBuilder();
-    sb.append("class CompletionPostRequest {\n");
-    sb.append("    config: ").append(toIndentedString(config)).append("\n");
-    sb.append("    placeholderValues: ").append(toIndentedString(placeholderValues)).append("\n");
-    sb.append("    messagesHistory: ").append(toIndentedString(messagesHistory)).append("\n");
-    cloudSdkCustomFields.forEach(
-        (k, v) ->
-            sb.append("    ").append(k).append(": ").append(toIndentedString(v)).append("\n"));
-    sb.append("}");
-    return sb.toString();
-  }
-
-  /**
-   * Convert the given object to string with each line indented by 4 spaces (except the first line).
-   */
-  private String toIndentedString(final java.lang.Object o) {
-    if (o == null) {
-      return "null";
-    }
-    return o.toString().replace("\n", "\n    ");
-  }
-
-  /**
-   * Create a type-safe, fluent-api builder object to construct a new {@link CompletionPostRequest}
-   * instance with all required arguments.
-   */
-  public static Builder create() {
-    return (config) -> new CompletionPostRequest().config(config);
-  }
-
-  /** Builder helper class. */
-  public interface Builder {
-    /**
-     * Set the config of this {@link CompletionPostRequest} instance.
-     *
-     * @param config The config of this {@link CompletionPostRequest}
-     * @return The CompletionPostRequest instance.
-     */
-    CompletionPostRequest config(@Nonnull final OrchestrationConfig config);
-  }
-}
+@JsonTypeInfo(use = JsonTypeInfo.Id.DEDUCTION)
+@JsonSubTypes({
+  @JsonSubTypes.Type(value = CompletionRequestConfiguration.class),
+  @JsonSubTypes.Type(value = CompletionRequestConfigurationReferenceById.class),
+  @JsonSubTypes.Type(value = CompletionRequestConfigurationReferenceByNameScenarioVersion.class),
+})
+public interface CompletionPostRequest {}