Openapi generator orchestration (#146)

* All hail the new orchestration client

* Leftovers

* Update code generatino ADR

* Minor comments

* Formatting

* Add javadoc and logging

* Added. More. Javadoc.

* Update sample HTML page

* Switch to error for empty content filter configs

* Simplify Exception

* Fix finish reason

* Fix type of Orchestration Response Messages

* Minor improvements

* Switch to deployment

* Update pom for using OSS generator

* Using original orchestration spec. Test contain descriminator

* Used OpenAPI generator for orchestration

* Using discriminator spec everywhere. test success.

* LLMModule specific deserializer ready. Test success.

* Generalized Fallback deserializer ready. Test success.

* OSS generator on customer facing orchestration spec

- Introduce a generic fallback and LLMModuleResult specific
  deserializers.

- Generator ignoring all interfaces

- Adapt jackson annotations

* Merging changes from main

* Merging changes from main

* Merging changes from main

* Formatting

* Clean up

- Remove Generic fallback deserializer
- Beta Annotation on all concrete model classes.
- Introduce Mixin to override model annotations
- Improve variable naming

* Update generated models

* Add test and improve deserializer

- Make deserializer lenient to allowed values

* [Orchestration] OSS Generator Improvements (#158)

* Simplifications and cleanup

* Remove parsing for streaming

* Reduce visibility of mixin class

* replace solution with custom deserializer to mixin

* remove unnecessary dependency jackson-databind-nullable

* Minor newline-reduction

* Minor syntax sugar

---------

Co-authored-by: Matthias Kuhr <[email protected]>
Co-authored-by: SAP Cloud SDK Bot <[email protected]>
Co-authored-by: Roshin Rajan Panackal <[email protected]>
Co-authored-by: I538344 <[email protected]>
Co-authored-by: Matthias Kuhr <[email protected]>
Co-authored-by: Alexander Dümont <[email protected]>
Co-authored-by: Alexander Dümont <[email protected]>

Author: 6 people

.gitignore

@@ -26,4 +26,6 @@
 .java-version
 
 ### Environment ###
-*.env
+*.env
+
+.openapi-generator

orchestration/.openapi-generator-ignore

@@ -0,0 +1,18 @@
+# OpenAPI Generator Ignore
+
+.github/
+gradle/
+.gitignore
+.travis.yml
+build.gradle
+build.sbt
+git_push.sh
+gradle.properties
+gradlew
+gradlew.bat
+pom.xml
+README.md
+settings.gradle
+src/main/AndroidManifest.xml
+api/
+.openapi-generator/

orchestration/pom.xml

@@ -85,6 +85,14 @@
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
     </dependency>
+    <dependency>
+      <groupId>javax.annotation</groupId>
+      <artifactId>javax.annotation-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.google.guava</groupId>
+      <artifactId>guava</artifactId>
+    </dependency>
 
     <!-- TODO: only needed for JsonObjectMapperBuilder, maybe we can use Jackson natively to avoid this dependency -->
     <dependency>
@@ -132,38 +140,72 @@
       <build>
         <plugins>
           <plugin>
-            <groupId>com.sap.cloud.sdk.datamodel</groupId>
+            <groupId>org.openapitools</groupId>
             <artifactId>openapi-generator-maven-plugin</artifactId>
-            <configuration>
-              <skip>true</skip>
-              <!-- skip automatic generation until we can omit API classes from code generation -->
-              <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
-              <apiMaturity>beta</apiMaturity>
-              <enableOneOfAnyOfGeneration>true</enableOneOfAnyOfGeneration>
-              <compileScope>COMPILE</compileScope>
-              <deleteOutputDirectory>true</deleteOutputDirectory>
-            </configuration>
             <executions>
               <execution>
-                <id>orchestration</id>
                 <goals>
                   <goal>generate</goal>
                 </goals>
                 <phase>generate-sources</phase>
                 <configuration>
+                  <!-- Specify the input OpenAPI spec file -->
                   <inputSpec>${project.basedir}/src/main/resources/spec/orchestration.yaml</inputSpec>
-                  <apiPackage>com.sap.ai.sdk.orchestration.client</apiPackage>
+                  <output>${project.basedir}</output>
+                  <!-- Specify the generator to use, e.g., java, spring, kotlin, etc. -->
+                  <generatorName>java</generatorName>
+                  <!-- Specify the package names for models, APIs, and invokers -->
                   <modelPackage>com.sap.ai.sdk.orchestration.client.model</modelPackage>
-                  <additionalProperties>
-                    <pojoBuilderMethodName>create</pojoBuilderMethodName>
-                    <pojoBuildMethodName/>
-                    <pojoConstructorVisibility>protected</pojoConstructorVisibility>
+                  <apiPackage>com.sap.ai.sdk.orchestration.client.api</apiPackage>
+                  <invokerPackage>com.sap.ai.sdk.orchestration.client.invoker</invokerPackage>
+
+                  <!-- Global properties level; can be unpacked with 'generate' prefix-->
+                  <globalProperties>
+                    <apiDocs>false</apiDocs>
+                    <modelDocs>false</modelDocs>
+                    <modelTests>false</modelTests>
+                    <apiTests>false</apiTests>
+                    <minimalUpdate>true</minimalUpdate>
+                  </globalProperties>
+
+                  <!-- Generator Specific properties level; some can be unpacked-->
+                  <configOptions>
+                    <generateBuilders>true</generateBuilders>
+                    <failOnUnknownProperties>false</failOnUnknownProperties>
+                    <hideGenerationTimestamp>true</hideGenerationTimestamp>
+                    <disallowAdditionalPropertiesIfNotPresent>false</disallowAdditionalPropertiesIfNotPresent>
                     <enumUnknownDefaultCase>true</enumUnknownDefaultCase>
-                  </additionalProperties>
+                    <useBeanValidation>false</useBeanValidation>
+                    <useOneOfInterfaces>true</useOneOfInterfaces>
+                    <additionalModelTypeAnnotations>@com.google.common.annotations.Beta</additionalModelTypeAnnotations>
+                  </configOptions>
+                  <generateModels>true</generateModels>
+                  <generateSupportingFiles>false</generateSupportingFiles>
+                  <generateApis>false</generateApis>
+                  <library>resttemplate</library>
+                  <!--<configHelp>true</configHelp>-->
                 </configuration>
               </execution>
             </executions>
           </plugin>
+          <plugin>
+            <artifactId>maven-clean-plugin</artifactId>
+            <configuration>
+              <filesets>
+                <fileset>
+                  <directory>${project.basedir}/src/main/java/com/sap/ai/sdk/orchestration/client</directory>
+                  <includes>
+                    <include>**/*</include>
+                  </includes>
+                </fileset>
+              </filesets>
+            </configuration>
+            <executions>
+              <execution>
+                <id>delete-orchestration-generated-client</id>
+              </execution>
+            </executions>
+          </plugin>
         </plugins>
       </build>
     </profile>

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

@@ -1,8 +1,10 @@
 package com.sap.ai.sdk.orchestration;
 
+import com.sap.ai.sdk.orchestration.client.model.ChatMessage;
 import com.sap.ai.sdk.orchestration.client.model.CompletionPostRequest;
 import com.sap.ai.sdk.orchestration.client.model.ModuleConfigs;
 import com.sap.ai.sdk.orchestration.client.model.OrchestrationConfig;
+import com.sap.ai.sdk.orchestration.client.model.Template;
 import com.sap.ai.sdk.orchestration.client.model.TemplatingModuleConfig;
 import io.vavr.control.Option;
 import java.util.ArrayList;
@@ -25,9 +27,9 @@ static CompletionPostRequest toCompletionPostRequest(
     // subsequent requests
     val configCopy = config.withTemplateConfig(template);
 
-    return CompletionPostRequest.create()
+    return new CompletionPostRequest()
         .orchestrationConfig(
-            OrchestrationConfig.create().moduleConfigurations(toModuleConfigs(configCopy)))
+            new OrchestrationConfig().moduleConfigurations(toModuleConfigs(configCopy)))
         .inputParams(prompt.getTemplateParameters())
         .messagesHistory(prompt.getMessagesHistory());
   }
@@ -42,14 +44,14 @@ static TemplatingModuleConfig toTemplateModuleConfig(
      * In this case, the request will fail, since the templating module will try to resolve the parameter.
      * To be fixed with https://github.tools.sap/AI/llm-orchestration/issues/662
      */
-    val messages = Option.of(template).map(TemplatingModuleConfig::getTemplate).getOrElse(List::of);
+    val messages = template instanceof Template t ? t.getTemplate() : List.<ChatMessage>of();
     val messagesWithPrompt = new ArrayList<>(messages);
     messagesWithPrompt.addAll(prompt.getMessages());
     if (messagesWithPrompt.isEmpty()) {
       throw new IllegalStateException(
           "A prompt is required. Pass at least one message or configure a template with messages or a template reference.");
     }
-    return TemplatingModuleConfig.create().template(messagesWithPrompt);
+    return new Template().template(messagesWithPrompt);
   }
 
   @Nonnull
@@ -60,7 +62,7 @@ static ModuleConfigs toModuleConfigs(@Nonnull final OrchestrationModuleConfig co
 
     //noinspection DataFlowIssue the template is always non-null here
     val moduleConfig =
-        ModuleConfigs.create()
+        new ModuleConfigs()
             .llmModuleConfig(llmConfig)
             .templatingModuleConfig(config.getTemplateConfig());
 

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

@@ -0,0 +1,10 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.sap.ai.sdk.orchestration.client.model.LLMModuleResultSynchronous;
+
+/** Mixin to enforce a specific subtype to be deserialized always. */
+@JsonTypeInfo(use = JsonTypeInfo.Id.NONE)
+@JsonDeserialize(as = LLMModuleResultSynchronous.class)
+interface LLMModuleResultMixIn {}

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

@@ -0,0 +1,7 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+
+/** Mixin to suppress @JsonTypeInfo for oneOf interfaces. */
+@JsonTypeInfo(use = JsonTypeInfo.Id.NONE)
+interface NoTypeInfoMixin {}

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

@@ -10,8 +10,13 @@
 import com.sap.ai.sdk.core.AiCoreService;
 import com.sap.ai.sdk.orchestration.client.model.CompletionPostRequest;
 import com.sap.ai.sdk.orchestration.client.model.CompletionPostResponse;
+import com.sap.ai.sdk.orchestration.client.model.FilterConfig;
+import com.sap.ai.sdk.orchestration.client.model.LLMModuleResult;
+import com.sap.ai.sdk.orchestration.client.model.MaskingProviderConfig;
 import com.sap.ai.sdk.orchestration.client.model.ModuleConfigs;
+import com.sap.ai.sdk.orchestration.client.model.ModuleResultsOutputUnmaskingInner;
 import com.sap.ai.sdk.orchestration.client.model.OrchestrationConfig;
+import com.sap.ai.sdk.orchestration.client.model.TemplatingModuleConfig;
 import com.sap.cloud.sdk.cloudplatform.connectivity.ApacheHttpClient5Accessor;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationAccessException;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationNotFoundException;
@@ -40,6 +45,11 @@ public class OrchestrationClient {
             .visibility(PropertyAccessor.GETTER, JsonAutoDetect.Visibility.NONE)
             .visibility(PropertyAccessor.SETTER, JsonAutoDetect.Visibility.NONE)
             .serializationInclusion(JsonInclude.Include.NON_NULL)
+            .mixIn(LLMModuleResult.class, LLMModuleResultMixIn.class)
+            .mixIn(ModuleResultsOutputUnmaskingInner.class, NoTypeInfoMixin.class)
+            .mixIn(FilterConfig.class, NoTypeInfoMixin.class)
+            .mixIn(MaskingProviderConfig.class, NoTypeInfoMixin.class)
+            .mixIn(TemplatingModuleConfig.class, NoTypeInfoMixin.class)
             .build();
   }
 
@@ -66,6 +76,20 @@ public OrchestrationClient(@Nonnull final AiCoreDeployment deployment) {
     this.deployment = () -> deployment;
   }
 
+  /**
+   * Convert the given prompt and config into a low-level request data object. The data object
+   * allows for further customization before sending the request.
+   *
+   * @param prompt The {@link OrchestrationPrompt} to generate a completion for.
+   * @param config The {@link OrchestrationConfig } configuration to use for the completion.
+   * @return The low-level request data object to send to orchestration.
+   */
+  @Nonnull
+  public static CompletionPostRequest toCompletionPostRequest(
+      @Nonnull final OrchestrationPrompt prompt, @Nonnull final OrchestrationModuleConfig config) {
+    return ConfigToRequestTransformer.toCompletionPostRequest(prompt, config);
+  }
+
   /**
    * Generate a completion for the given prompt.
    *
@@ -118,20 +142,6 @@ public CompletionPostResponse executeRequest(@Nonnull final CompletionPostReques
     return executeRequest(postRequest);
   }
 
-  /**
-   * Convert the given prompt and config into a low-level request data object. The data object
-   * allows for further customization before sending the request.
-   *
-   * @param prompt The {@link OrchestrationPrompt} to generate a completion for.
-   * @param config The {@link OrchestrationConfig } configuration to use for the completion.
-   * @return The low-level request data object to send to orchestration.
-   */
-  @Nonnull
-  public static CompletionPostRequest toCompletionPostRequest(
-      @Nonnull final OrchestrationPrompt prompt, @Nonnull final OrchestrationModuleConfig config) {
-    return ConfigToRequestTransformer.toCompletionPostRequest(prompt, config);
-  }
-
   @Nonnull
   CompletionPostResponse executeRequest(@Nonnull final BasicClassicHttpRequest request) {
     try {

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

@@ -32,7 +32,7 @@ public class OrchestrationPrompt {
    * @param message A user message.
    */
   public OrchestrationPrompt(@Nonnull final String message) {
-    messages.add(ChatMessage.create().role("user").content(message));
+    messages.add(new ChatMessage().role("user").content(message));
   }
 
   /**

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

@@ -23,44 +23,6 @@
 class OrchestrationResponseHandler<T> implements HttpClientResponseHandler<T> {
   @Nonnull private final Class<T> responseType;
 
-  /**
-   * Processes a {@link ClassicHttpResponse} and returns some value corresponding to that response.
-   *
-   * @param response The response to process
-   * @return A model class instantiated from the response
-   * @throws OrchestrationClientException in case of a problem or the connection was aborted
-   */
-  @Override
-  public T handleResponse(@Nonnull final ClassicHttpResponse response)
-      throws OrchestrationClientException {
-    if (response.getCode() >= 300) {
-      buildExceptionAndThrow(response);
-    }
-    val result = parseResponse(response);
-    log.debug("Received the following response from orchestration service: {}", result);
-    return result;
-  }
-
-  // The InputStream of the HTTP entity is closed by EntityUtils.toString
-  @SuppressWarnings("PMD.CloseResource")
-  @Nonnull
-  private T parseResponse(@Nonnull final ClassicHttpResponse response)
-      throws OrchestrationClientException {
-    final HttpEntity responseEntity = response.getEntity();
-    if (responseEntity == null) {
-      throw new OrchestrationClientException("Response from Orchestration service was empty.");
-    }
-    val content = getContent(responseEntity);
-    log.debug("Parsing response from JSON response: {}", content);
-    try {
-      return JACKSON.readValue(content, responseType);
-    } catch (final JsonProcessingException e) {
-      log.error("Failed to parse the following response from orchestration service: {}", content);
-      throw new OrchestrationClientException(
-          "Failed to parse response from orchestration service", e);
-    }
-  }
-
   @Nonnull
   private static String getContent(@Nonnull final HttpEntity entity) {
     try {
@@ -123,4 +85,42 @@ static void parseErrorAndThrow(
         "%s and error message: '%s'"
             .formatted(baseException.getMessage(), maybeError.get().getMessage()));
   }
+
+  /**
+   * Processes a {@link ClassicHttpResponse} and returns some value corresponding to that response.
+   *
+   * @param response The response to process
+   * @return A model class instantiated from the response
+   * @throws OrchestrationClientException in case of a problem or the connection was aborted
+   */
+  @Override
+  public T handleResponse(@Nonnull final ClassicHttpResponse response)
+      throws OrchestrationClientException {
+    if (response.getCode() >= 300) {
+      buildExceptionAndThrow(response);
+    }
+    val result = parseResponse(response);
+    log.debug("Received the following response from orchestration service: {}", result);
+    return result;
+  }
+
+  // The InputStream of the HTTP entity is closed by EntityUtils.toString
+  @SuppressWarnings("PMD.CloseResource")
+  @Nonnull
+  private T parseResponse(@Nonnull final ClassicHttpResponse response)
+      throws OrchestrationClientException {
+    final HttpEntity responseEntity = response.getEntity();
+    if (responseEntity == null) {
+      throw new OrchestrationClientException("Response from Orchestration service was empty.");
+    }
+    val content = getContent(responseEntity);
+    log.debug("Parsing response from JSON response: {}", content);
+    try {
+      return JACKSON.readValue(content, responseType);
+    } catch (final JsonProcessingException e) {
+      log.error("Failed to parse the following response from orchestration service: {}", content);
+      throw new OrchestrationClientException(
+          "Failed to parse response from orchestration service", e);
+    }
+  }
 }