feat: [Orchestration] Added support for transforming a JSON output into an entity

Author: CharlesDuboisSAP

docs/release_notes.md

@@ -13,7 +13,7 @@
 
 ### ✨ New Functionality
 
--
+- [Orchestration] Added support for [transforming a JSON output into an entity](https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion#json_schema)
 
 ### 📈 Improvements
 

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

@@ -2,6 +2,8 @@
 
 import static lombok.AccessLevel.PACKAGE;
 
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import com.sap.ai.sdk.orchestration.model.AssistantChatMessage;
 import com.sap.ai.sdk.orchestration.model.ChatMessage;
 import com.sap.ai.sdk.orchestration.model.ChatMessageContent;
@@ -107,4 +109,24 @@ public LLMChoice getChoice() {
         .getChoices()
         .get(0);
   }
+
+  /**
+   * Transform a JSON response into an entity of the given type.
+   *
+   * <p>This is possible on a request with a {@link OrchestrationTemplate#withJsonSchemaResponse}
+   * configured into {@link OrchestrationModuleConfig#withTemplateConfig}.
+   *
+   * @param type the class type to deserialize the JSON content into.
+   * @return the deserialized entity of type T.
+   * @param <T> the type of the entity to deserialize to.
+   */
+  @Nonnull
+  public <T> T entity(@Nonnull final Class<T> type) {
+    try {
+      return new ObjectMapper().readValue(getContent(), type);
+    } catch (JsonProcessingException e) {
+      throw new OrchestrationClientException(
+          "Failed to deserialize the JSON content: " + e.getMessage(), e);
+    }
+  }
 }

sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/OrchestrationController.java

@@ -239,11 +239,7 @@ Object groundingHelpSapCom(
   @Nonnull
   Object responseFormatJsonSchema(
       @RequestParam(value = "format", required = false) final String format) {
-    final var response = service.responseFormatJsonSchema("apple");
-    if ("json".equals(format)) {
-      return response;
-    }
-    return response.getContent();
+    return service.responseFormatJsonSchema("apple");
   }
 
   @GetMapping("/responseFormatJsonObject")

sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OrchestrationService.java

@@ -382,23 +382,28 @@ public OrchestrationChatResponse groundingHelpSapCom(@Nonnull final String userM
     return client.chatCompletion(prompt, configWithGrounding);
   }
 
+  /**
+   * A simple record to demonstrate the response format feature of the orchestration service.
+   *
+   * @param translation the translated text
+   * @param language the language of the translation
+   */
+  public record Translation(
+      @JsonProperty(required = true) String translation,
+      @JsonProperty(required = true) String language) {}
+
   /**
    * Chat request to OpenAI through the Orchestration service using response format with JSON
    * schema.
    *
+   * @param word the word to translate
+   * @return the assistant response object
    * @link <a
    *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/structured-output">SAP
    *     AI Core: Orchestration - Structured Output</a>
-   * @param word the word to translate
-   * @return the assistant response object
    */
   @Nonnull
-  public OrchestrationChatResponse responseFormatJsonSchema(@Nonnull final String word) {
-    //    Example class
-    record Translation(
-        @JsonProperty(required = true) String translation,
-        @JsonProperty(required = true) String language) {}
-
+  public Translation responseFormatJsonSchema(@Nonnull final String word) {
     val schema =
         ResponseJsonSchema.fromType(Translation.class)
             .withDescription("Output schema for language translation.")
@@ -411,7 +416,7 @@ record Translation(
             Message.user("Whats '%s' in German?".formatted(word)),
             Message.system("You are a language translator."));
 
-    return client.chatCompletion(prompt, configWithResponseSchema);
+    return client.chatCompletion(prompt, configWithResponseSchema).entity(Translation.class);
   }
 
   /**

sample-code/spring-app/src/test/java/com/sap/ai/sdk/app/controllers/OrchestrationTest.java

@@ -7,6 +7,7 @@
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 import com.sap.ai.sdk.app.services.OrchestrationService;
+import com.sap.ai.sdk.app.services.OrchestrationService.Translation;
 import com.sap.ai.sdk.orchestration.AzureContentFilter;
 import com.sap.ai.sdk.orchestration.AzureFilterThreshold;
 import com.sap.ai.sdk.orchestration.DpiMasking;
@@ -317,9 +318,9 @@ void testMultiStringInput() {
 
   @Test
   void testResponseFormatJsonSchema() {
-    val result = service.responseFormatJsonSchema("apple").getOriginalResponse();
-    val choices = ((LLMModuleResultSynchronous) result.getOrchestrationResult()).getChoices();
-    assertThat(choices.get(0).getMessage().getContent()).isNotEmpty();
+    Translation translation = service.responseFormatJsonSchema("apple");
+    assertThat(translation.translation()).isNotEmpty();
+    assertThat(translation.language()).isNotEmpty();
   }
 
   @Test