feat: [Orchestration] Convenience for response format (#341)

* Use library to generate schemas from java classes

* Create ResponseJsonSchema and adapt OrchestrationModuleConfig

* Add additional tests, reset TestCoverage

* Add documentation etc.

* Small fixes

* Improve documentation

* Requested changes

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

Co-authored-by: Charles Dubois <[email protected]>

* Small fix

* WIP

* Introduce new class TemplateConfig and adapt tests

* Adding javadocs and annotations

* Add tests

* Update docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

Co-authored-by: Alexander Dümont <[email protected]>

* Small changes

* Update orchestration/src/main/java/com/sap/ai/sdk/orchestration/ResponseJsonSchema.java

Co-authored-by: Alexander Dümont <[email protected]>

* Formatting

* Use functional interfaces instead of class (#357)

Co-authored-by: Alexander Dümont <[email protected]>
Co-authored-by: Jonas-Isr <[email protected]>

* Requested changes

* change @SInCE to 1.4.0

* rename factory methods

* small fix

* small fix.finalfinal

---------

Co-authored-by: Jonas Israel <[email protected]>
Co-authored-by: Charles Dubois <[email protected]>
Co-authored-by: Alexander Dümont <[email protected]>
Co-authored-by: SAP Cloud SDK Bot <[email protected]>
Co-authored-by: Alexander Dümont <[email protected]>

Author: 5 people

.pipeline/spotbugs-exclusions.xml

@@ -9,4 +9,9 @@
       <Package name="com.sap.ai.sdk.grounding.model"/>
     </Or>
   </Match>
+  <Match>
+    <Class name="com.sap.ai.sdk.orchestration.ResponseJsonSchema" />
+    <Method name="withStrict" />
+    <Bug pattern="RC_REF_COMPARISON_BAD_PRACTICE_BOOLEAN" />
+  </Match>
 </FindBugsFilter>

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -311,20 +311,15 @@ It is possible to set the response format for the chat completion. Available opt
 Setting the response format to `JSON_OBJECT` tells the AI to respond with JSON, i.e., the response from the AI will be a string consisting of a valid JSON. This does, however, not guarantee that the response adheres to a specific structure (other than being valid JSON).
 
 ```java
-var template = Message.user("What is 'apple' in German?");
-var templatingConfig =
-        Template.create()
-                .template(List.of(template.createChatMessage()))
-                .responseFormat(
-                        ResponseFormatJsonObject.create()
-                                .type(ResponseFormatJsonObject.TypeEnum.JSON_OBJECT));
-var configWithTemplate = llmWithImageSupportConfig.withTemplateConfig(templatingConfig);
+var config = new OrchestrationModuleConfig()
+        .withLlmConfig(OrchestrationAiModel.GPT_4O);
+var configWithJsonResponse = 
+        config.withTemplateConfig(TemplateConfig.create().withJsonResponse());
 
 var prompt =
         new OrchestrationPrompt(
-                Message.system(
-                        "You are a language translator. Answer using the following JSON format: {\"language\": ..., \"translation\": ...}"));
-var response = client.chatCompletion(prompt, configWithTemplate).getContent();
+                Message.user("Some message."), Message.system("Answer using JSON."));
+var response = client.chatCompletion(prompt, configWithJsonResponse).getContent();
 ```
 Note, that it is necessary to tell the AI model to actually return a JSON object in the prompt. The result might not adhere exactly to the given JSON format, but it will be a JSON object.
 
@@ -334,38 +329,41 @@ Note, that it is necessary to tell the AI model to actually return a JSON object
 If you want the response to not only consist of valid JSON but additionally adhere to a specific JSON schema, you can use `JSON_SCHEMA`. in order to do that, add a JSON schema to the configuration as shown below and the response will adhere to the given schema.
 
 ```java
-var template = Message.user("Whats '%s' in German?".formatted(word));
 var schema =
-        Map.of(
-                "type",
-                "object",
-                "properties",
-                Map.of(
-                        "language", Map.of("type", "string"),
-                        "translation", Map.of("type", "string")),
-                "required",
-                List.of("language", "translation"),
-                "additionalProperties",
-                false);
-
-// Note, that we plan to add more convenient ways to add a JSON schema in the future.
-var templatingConfig =
-        Template.create()
-                .template(List.of(template.createChatMessage()))
-                .responseFormat(
-                        ResponseFormatJsonSchema.create()
-                                .type(ResponseFormatJsonSchema.TypeEnum.JSON_SCHEMA)
-                                .jsonSchema(
-                                        ResponseFormatJsonSchemaJsonSchema.create()
-                                                .name("translation_response")
-                                                .schema(schema)
-                                                .strict(true)
-                                                .description("Output schema for language translation.")));
-var configWithTemplate = llmWithImageSupportConfig.withTemplateConfig(templatingConfig);
-
-var prompt = new OrchestrationPrompt(Message.system("You are a language translator."));
+    ResponseJsonSchema.fromType(MyClass.class)
+            .withDescription("Output schema for the example class MyClass.")
+            .withStrict(true);
+var config = new OrchestrationModuleConfig()
+        .withLlmConfig(OrchestrationAiModel.GPT_4O);
+var configWithResponseSchema =
+        config.withTemplateConfig(TemplateConfig.create().withJsonSchemaResponse(schema));
+
+var prompt = new OrchestrationPrompt(Message.user("Some message."));
 var response = client.chatCompletion(prompt, configWithTemplate).getContent();
 ```
+Note, that the LLM will only exactly adhere to the given schema if you use `withStrict(true)`. Not all schemas are possible for OpenAI in strict mode. See [here](https://platform.openai.com/docs/guides/structured-outputs#supported-schemas) for more information.
+
+There is also a way to generate the schema from a map of key-value pairs. This can be done as follows:
+<details><summary>Click to expand code</summary>
+
+```java
+var schemaMap =
+    Map.ofEntries(
+        entry("type", "object"),
+        entry("properties", Map.ofEntries(
+            entry("language", Map.of("type", "string")),
+            entry("translation", Map.of("type", "string"))),
+        entry("required", List.of("language","translation")),
+        entry("additionalProperties", false)));
+
+var schemaFromMap = ResponseJsonSchema.fromMap(schemaMap, "Translator-Schema");
+var config = new OrchestrationModuleConfig()
+    .withLlmConfig(OrchestrationAiModel.GPT_4O);
+var configWithResponseSchema = 
+        config.withTemplateConfig(TemplateConfig.create().withJsonSchemaResponse(schemaFromMap));
+```
+
+</details>
 
 Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OrchestrationService.java)
 

docs/release-notes/release_notes.md

@@ -15,7 +15,9 @@
 
 ### ✨ New Functionality
 
-- [Orchestration] [Add Spring AI tool calling](../guides/SPRING_AI_INTEGRATION.md#tool-calling).
+- [Orchestration] 
+    - [Add Spring AI tool calling](../guides/SPRING_AI_INTEGRATION.md#tool-calling).
+    - [Add new convenient methods to set the response format for Orchestration.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#set-a-response-format)
 - [Document Grounding] [Add Document Grounding Client](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/GROUNDING.md)
     - `com.sap.ai.sdk:document-grounding:1.4.0`
 - [OpenAI]

orchestration/pom.xml

@@ -31,11 +31,11 @@
   </developers>
   <properties>
     <project.rootdir>${project.basedir}/../</project.rootdir>
-    <coverage.complexity>81%</coverage.complexity>
-    <coverage.line>92%</coverage.line>
-    <coverage.instruction>93%</coverage.instruction>
-    <coverage.branch>74%</coverage.branch>
-    <coverage.method>92%</coverage.method>
+    <coverage.complexity>82%</coverage.complexity>
+    <coverage.line>93%</coverage.line>
+    <coverage.instruction>94%</coverage.instruction>
+    <coverage.branch>76%</coverage.branch>
+    <coverage.method>93%</coverage.method>
     <coverage.class>100%</coverage.class>
   </properties>
 
@@ -100,6 +100,14 @@
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
     </dependency>
+    <dependency>
+      <groupId>com.github.victools</groupId>
+      <artifactId>jsonschema-generator</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.github.victools</groupId>
+      <artifactId>jsonschema-module-jackson</artifactId>
+    </dependency>
     <!-- scope "provided" -->
     <dependency>
       <groupId>org.projectlombok</groupId>

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

@@ -1,5 +1,6 @@
 package com.sap.ai.sdk.orchestration;
 
+import com.google.common.annotations.Beta;
 import com.sap.ai.sdk.orchestration.model.FilteringModuleConfig;
 import com.sap.ai.sdk.orchestration.model.GroundingModuleConfig;
 import com.sap.ai.sdk.orchestration.model.InputFilteringConfig;
@@ -211,4 +212,21 @@ public OrchestrationModuleConfig withGrounding(
       @Nonnull final GroundingProvider groundingProvider) {
     return this.withGroundingConfig(groundingProvider.createConfig());
   }
+
+  /**
+   * Creates a new configuration with the given template configuration as {@link TemplateConfig}.
+   *
+   * @link <a href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/templating">SAP
+   *     AI Core: Orchestration - Templating</a>
+   * @param templateConfig The template configuration to use.
+   * @return A new configuration with the given template configuration.
+   * @since 1.4.0
+   */
+  @Tolerate
+  @Nonnull
+  @Beta
+  public OrchestrationModuleConfig withTemplateConfig(
+      @Nonnull final TemplateConfig templateConfig) {
+    return this.withTemplateConfig(templateConfig.toLowLevel());
+  }
 }

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

@@ -0,0 +1,96 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.orchestration.model.ChatCompletionTool;
+import com.sap.ai.sdk.orchestration.model.ChatMessage;
+import com.sap.ai.sdk.orchestration.model.ResponseFormatJsonObject;
+import com.sap.ai.sdk.orchestration.model.ResponseFormatJsonSchema;
+import com.sap.ai.sdk.orchestration.model.ResponseFormatJsonSchemaJsonSchema;
+import com.sap.ai.sdk.orchestration.model.Template;
+import com.sap.ai.sdk.orchestration.model.TemplateResponseFormat;
+import com.sap.ai.sdk.orchestration.model.TemplatingModuleConfig;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+import lombok.Value;
+import lombok.With;
+import lombok.val;
+
+/**
+ * A template to use in {@link OrchestrationModuleConfig}.
+ *
+ * @since 1.4.0
+ */
+@EqualsAndHashCode(callSuper = true)
+@Value
+@With
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+@NoArgsConstructor(force = true, access = AccessLevel.PACKAGE)
+@Beta
+public class OrchestrationTemplate extends TemplateConfig {
+  @Nullable List<ChatMessage> template;
+  @Nullable Map<String, String> defaults;
+
+  @With(AccessLevel.PRIVATE)
+  @Nullable
+  TemplateResponseFormat responseFormat;
+
+  @Nullable List<ChatCompletionTool> tools;
+
+  /**
+   * Create a low-level representation of the template.
+   *
+   * @return The low-level representation of the template.
+   */
+  @Override
+  @Nonnull
+  protected TemplatingModuleConfig toLowLevel() {
+    final List<ChatMessage> template = this.template != null ? this.template : List.of();
+    final Map<String, String> defaults = this.defaults != null ? this.defaults : new HashMap<>();
+    final List<ChatCompletionTool> tools = this.tools != null ? this.tools : new ArrayList<>();
+    return Template.create()
+        .template(template)
+        .defaults(defaults)
+        .responseFormat(responseFormat)
+        .tools(tools);
+  }
+
+  /**
+   * Set the response format to the given JSON schema.
+   *
+   * @param schema The JSON schema to use.
+   * @return The updated template.
+   */
+  @Nonnull
+  public OrchestrationTemplate withJsonSchemaResponse(@Nonnull final ResponseJsonSchema schema) {
+    val responseFormatJsonSchema =
+        ResponseFormatJsonSchema.create()
+            .type(ResponseFormatJsonSchema.TypeEnum.JSON_SCHEMA)
+            .jsonSchema(
+                ResponseFormatJsonSchemaJsonSchema.create()
+                    .name(schema.getName())
+                    .schema(schema.getSchemaMap())
+                    .strict(schema.getStrict())
+                    .description(schema.getDescription()));
+    return this.withResponseFormat(responseFormatJsonSchema);
+  }
+
+  /**
+   * Set the response format to JSON object.
+   *
+   * @return The updated template.
+   */
+  @Nonnull
+  public OrchestrationTemplate withJsonResponse() {
+    val responseFormatJsonObject =
+        ResponseFormatJsonObject.create().type(ResponseFormatJsonObject.TypeEnum.JSON_OBJECT);
+    return this.withResponseFormat(responseFormatJsonObject);
+  }
+}

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

@@ -0,0 +1,35 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.orchestration.model.TemplateRef;
+import com.sap.ai.sdk.orchestration.model.TemplateRefTemplateRef;
+import com.sap.ai.sdk.orchestration.model.TemplatingModuleConfig;
+import javax.annotation.Nonnull;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Value;
+
+/**
+ * A reference to a template to use in {@link OrchestrationModuleConfig}.
+ *
+ * @since 1.4.0
+ */
+@EqualsAndHashCode(callSuper = true)
+@Value
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
+@Beta
+public class OrchestrationTemplateReference extends TemplateConfig {
+  @Nonnull TemplateRefTemplateRef reference;
+
+  /**
+   * Create a low-level representation of the template.
+   *
+   * @return The low-level representation of the template.
+   */
+  @Nonnull
+  @Override
+  protected TemplatingModuleConfig toLowLevel() {
+    return TemplateRef.create().templateRef(reference);
+  }
+}

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

@@ -0,0 +1,75 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.github.victools.jsonschema.generator.Option;
+import com.github.victools.jsonschema.generator.OptionPreset;
+import com.github.victools.jsonschema.generator.SchemaGenerator;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
+import com.github.victools.jsonschema.generator.SchemaVersion;
+import com.github.victools.jsonschema.module.jackson.JacksonModule;
+import com.github.victools.jsonschema.module.jackson.JacksonOption;
+import com.google.common.annotations.Beta;
+import java.lang.reflect.Type;
+import java.util.Map;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Value;
+import lombok.With;
+import lombok.val;
+
+/**
+ * The schema object to use for the response format parameter in {@link OrchestrationTemplate}.
+ *
+ * @since 1.4.0
+ */
+@Value
+@AllArgsConstructor(access = AccessLevel.PACKAGE)
+@With
+@Beta
+public class ResponseJsonSchema {
+  @Nonnull Map<String, Object> schemaMap;
+  @Nonnull String name;
+  @Nullable String description;
+  @Nullable Boolean strict;
+
+  /**
+   * Create a new instance of {@link ResponseJsonSchema} with the given schema map and name.
+   *
+   * @param schemaMap The schema map
+   * @param name The name of the schema
+   * @return The new instance of {@link ResponseJsonSchema}
+   */
+  @Nonnull
+  public static ResponseJsonSchema fromMap(
+      @Nonnull final Map<String, Object> schemaMap, @Nonnull final String name) {
+    return new ResponseJsonSchema(schemaMap, name, null, null);
+  }
+
+  /**
+   * Create a new instance of {@link ResponseJsonSchema} from a given class.
+   *
+   * @param classType The class to generate the schema from
+   * @return The new instance of {@link ResponseJsonSchema}
+   */
+  @Nonnull
+  public static ResponseJsonSchema fromType(@Nonnull final Type classType) {
+    val module =
+        new JacksonModule(
+            JacksonOption.RESPECT_JSONPROPERTY_REQUIRED, JacksonOption.RESPECT_JSONPROPERTY_ORDER);
+    val generator =
+        new SchemaGenerator(
+            new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON)
+                .without(Option.SCHEMA_VERSION_INDICATOR)
+                .with(Option.FORBIDDEN_ADDITIONAL_PROPERTIES_BY_DEFAULT)
+                .with(module)
+                .build());
+    val jsonSchema = generator.generateSchema(classType);
+    val mapper = new ObjectMapper();
+    val schemaMap = mapper.convertValue(jsonSchema, new TypeReference<Map<String, Object>>() {});
+    val schemaName = ((Class<?>) classType).getSimpleName() + "-Schema";
+    return new ResponseJsonSchema(schemaMap, schemaName, null, null);
+  }
+}