fix!: Refactor ConvertDocumentResponse for polymorphic deserialization based on docling-serve API response

.github/project.yml

@@ -1,4 +1,4 @@
 release:
   previous-version: 0.4.7
-  current-version: 0.4.8
-  next-version: 0.4.9
+  current-version: 0.5.0
+  next-version: 0.5.1

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeConvertApi.java

@@ -21,7 +21,7 @@ public interface DoclingServeConvertApi {
    * Converts the provided document source(s) into a processed document based on the specified options.
    *
    * @param request the {@link ConvertDocumentRequest} containing the source(s), conversion options, and optional target.
-   * @return a {@link ConvertDocumentResponse} containing the processed document data, processing details, and any errors.
+   * @return a {@link ConvertDocumentResponse} describing the convert document response.
    * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   ConvertDocumentResponse convertSource(ConvertDocumentRequest request);

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeTaskApi.java

@@ -32,7 +32,7 @@ public interface DoclingServeTaskApi {
   TaskStatusPollResponse pollTaskStatus(TaskStatusPollRequest request);
 
   /**
-   * Converts the result of a completed task into a document format as specified in the request.
+   * Returns the result of a completed convert task.
    *
    * This method processes the task result identified by the unique task ID provided in
    * the request, performs any necessary transformation, and returns a response

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ConvertDocumentResponse.java

@@ -1,90 +1,33 @@
 package ai.docling.serve.api.convert.response;
 
-import java.util.List;
-import java.util.Map;
-
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonSetter;
-import com.fasterxml.jackson.annotation.Nulls;
+import com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
 
 /**
- * Response returned by the Convert API for a single conversion request.
+ * Abstract response returned by the Convert API for a single conversion request.
  *
  * <p>Serialization uses {@link JsonInclude.Include#NON_EMPTY}, so nulls and empty
  * collections/strings are omitted from JSON output.</p>
  */
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
-@tools.jackson.databind.annotation.JsonDeserialize(builder = ConvertDocumentResponse.Builder.class)
-@lombok.extern.jackson.Jacksonized
-@lombok.Builder(toBuilder = true)
-@lombok.Getter
-@lombok.ToString
-public class ConvertDocumentResponse {
-  /**
-   * Converted document content.
-   *
-   * @param document the converted document
-   * @return the converted document
-   */
-  @JsonProperty("document")
-  private DocumentResponse document;
-
+@JsonTypeInfo(
+    use = JsonTypeInfo.Id.DEDUCTION
+)
+@JsonSubTypes({
+    @JsonSubTypes.Type(InBodyConvertDocumentResponse.class),
+    @JsonSubTypes.Type(PreSignedUrlConvertDocumentResponse.class),
+    @JsonSubTypes.Type(ZipArchiveConvertDocumentResponse.class)
+})
+public abstract sealed class ConvertDocumentResponse permits InBodyConvertDocumentResponse, PreSignedUrlConvertDocumentResponse,
+    ZipArchiveConvertDocumentResponse {
   /**
-   * List of errors that occurred during conversion.
+   * Type of response
    *
-   * @param errors the list of errors
-   * @return the list of errors
+   * @return the response type
    */
-  @JsonProperty("errors")
-  @JsonSetter(nulls = Nulls.AS_EMPTY)
-  @lombok.Singular
-  private List<ErrorItem> errors;
+  @JsonProperty("response_type")
+  public abstract ResponseType getResponseType();
 
-  /**
-   * Total processing time in seconds.
-   *
-   * @param processingTime the processing time in seconds
-   * @return the processing time in seconds
-   */
-  @JsonProperty("processing_time")
-  private Double processingTime;
-
-  /**
-   * Conversion status (success, failure, partial_success, etc.).
-   *
-   * @param status the conversion status
-   * @return the conversion status
-   */
-  @JsonProperty("status")
-  private String status;
-
-  /**
-   * Detailed timing information for processing stages.
-   *
-   * @param timings the map of timing information
-   * @return the map of timing information
-   */
-  @JsonProperty("timings")
-  @JsonSetter(nulls = Nulls.AS_EMPTY)
-  @lombok.Singular
-  private Map<String, Object> timings;
-
-  /**
-   * Builder for creating {@link ConvertDocumentResponse} instances.
-   * Generated by Lombok's {@code @Builder} annotation.
-   * 
-   * <p>Builder methods:
-   * <ul>
-   *   <li>{@code document(DocumentResponse)} - Set the converted document</li>
-   *   <li>{@code error(ErrorItem)} - Add a single error (use with @Singular)</li>
-   *   <li>{@code errors(List<ErrorItem>)} - Set the list of errors</li>
-   *   <li>{@code processingTime(Double)} - Set the processing time in seconds</li>
-   *   <li>{@code status(String)} - Set the conversion status</li>
-   *   <li>{@code timing(String, Object)} - Add a single timing entry (use with @Singular)</li>
-   *   <li>{@code timings(Map<String, Object>)} - Set the map of timing information</li>
-   * </ul>
-   */
-  @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
-  public static class Builder { }
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/InBodyConvertDocumentResponse.java

@@ -0,0 +1,111 @@
+package ai.docling.serve.api.convert.response;
+
+import java.util.List;
+import java.util.Map;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonSetter;
+import com.fasterxml.jackson.annotation.Nulls;
+
+/**
+ * Response for single document conversions with in-body content delivery.
+ *
+ * <p>This response type is returned when both the following conditions hold:</p>
+ * <ul>
+ *   <li>The conversion request contains a single source</li>
+ *   <li>The target type is {@link ai.docling.serve.api.convert.request.target.InBodyTarget}</li>
+ * </ul>
+ *
+ * <p>The converted document content is included directly in the response body,
+ * along with conversion status, processing time, errors, and detailed timing
+ * information for each processing stage.</p>
+ *
+ * <p>Serialization uses {@link JsonInclude.Include#NON_EMPTY}, so nulls and empty
+ * collections/strings are omitted from JSON output.</p>
+ *
+ * @see ConvertDocumentResponse
+ * @see ResponseType#IN_BODY
+ * @see ai.docling.serve.api.convert.request.target.InBodyTarget
+ * @see DocumentResponse
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = InBodyConvertDocumentResponse.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public final class InBodyConvertDocumentResponse extends ConvertDocumentResponse {
+  /**
+   * Converted document content.
+   *
+   * @param document the converted document
+   * @return the converted document
+   */
+  @JsonProperty("document")
+  private DocumentResponse document;
+
+  /**
+   * List of errors that occurred during conversion.
+   *
+   * @param errors the list of errors
+   * @return the list of errors
+   */
+  @JsonProperty("errors")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private List<ErrorItem> errors;
+
+  /**
+   * Total processing time in seconds.
+   *
+   * @param processingTime the processing time in seconds
+   * @return the processing time in seconds
+   */
+  @JsonProperty("processing_time")
+  private Double processingTime;
+
+  /**
+   * Conversion status (success, failure, partial_success, etc.).
+   *
+   * @param status the conversion status
+   * @return the conversion status
+   */
+  @JsonProperty("status")
+  private String status;
+
+  /**
+   * Detailed timing information for processing stages.
+   *
+   * @param timings the map of timing information
+   * @return the map of timing information
+   */
+  @JsonProperty("timings")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private Map<String, Object> timings;
+
+  @Override
+  @lombok.ToString.Include
+  public ResponseType getResponseType() {
+    return ResponseType.IN_BODY;
+  }
+
+  /**
+   * Builder for creating {@link InBodyConvertDocumentResponse} instances.
+   * Generated by Lombok's {@code @Builder} annotation.
+   *
+   * <p>Builder methods:
+   * <ul>
+   *   <li>{@code document(DocumentResponse)} - Set the converted document</li>
+   *   <li>{@code error(ErrorItem)} - Add a single error (use with @Singular)</li>
+   *   <li>{@code errors(List<ErrorItem>)} - Set the list of errors</li>
+   *   <li>{@code processingTime(Double)} - Set the processing time in seconds</li>
+   *   <li>{@code status(String)} - Set the conversion status</li>
+   *   <li>{@code timing(String, Object)} - Add a single timing entry (use with @Singular)</li>
+   *   <li>{@code timings(Map<String, Object>)} - Set the map of timing information</li>
+   * </ul>
+   */
+  @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
+  public static class Builder { }
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/PreSignedUrlConvertDocumentResponse.java

@@ -0,0 +1,93 @@
+package ai.docling.serve.api.convert.response;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Response for document conversions with S3 or PUT target types.
+ *
+ * <p>This response type is returned when the conversion request specifies
+ * an S3 target or PUT target. The converted documents are stored in the
+ * specified location.
+ * The response includes processing statistics and conversion metrics.</p>
+ *
+ * <p>This response type is returned in any one the following scenarios:</p>
+ * <ul>
+ *   <li>Target type is {@link ai.docling.serve.api.convert.request.target.PutTarget}</li>
+ *   <li>Target type is {@link ai.docling.serve.api.convert.request.target.S3Target}</li>
+ * </ul>
+ *
+ * <p>Serialization uses {@link JsonInclude.Include#NON_EMPTY}, so nulls and empty
+ * collections/strings are omitted from JSON output.</p>
+ *
+ * @see ConvertDocumentResponse
+ * @see ResponseType#PRE_SIGNED_URL
+ * @see ai.docling.serve.api.convert.request.target.S3Target
+ * @see ai.docling.serve.api.convert.request.target.PutTarget
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = PreSignedUrlConvertDocumentResponse.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public final class PreSignedUrlConvertDocumentResponse extends ConvertDocumentResponse {
+
+  /**
+   * Total processing time in seconds.
+   *
+   * @param processingTime the processing time in seconds
+   * @return the processing time in seconds
+   */
+  @JsonProperty("processing_time")
+  private Double processingTime;
+
+  /**
+   * Number of attempted conversions
+   *
+   * @param num_converted the number of attempted conversions
+   * @return the number of attempted conversions
+   */
+  @JsonProperty("num_converted")
+  private Integer numConverted;
+
+  /**
+   * Number of successful conversions
+   *
+   * @param numSucceeded the number of successful conversions
+   * @return the number of successful conversions
+   */
+  @JsonProperty("num_succeeded")
+  private Integer numSucceeded;
+
+  /**
+   * Number of failed conversions
+   *
+   * @param numFailed the number of failed conversions
+   * @return the number of failed conversions
+   */
+  @JsonProperty("num_failed")
+  private Integer numFailed;
+
+  @Override
+  @lombok.ToString.Include
+  public ResponseType getResponseType() {
+    return ResponseType.PRE_SIGNED_URL;
+  }
+
+  /**
+   * Builder for creating {@link PreSignedUrlConvertDocumentResponse} instances.
+   * Generated by Lombok's {@code @Builder} annotation.
+   *
+   * <p>Builder methods:
+   * <ul>
+   *   <li>{@code processingTime(Double)} - Set the total processing time in seconds</li>
+   *   <li>{@code numConverted(Integer)} - Set the number of attempted conversions</li>
+   *   <li>{@code numSucceeded(Integer)} - Set the number of successful conversions</li>
+   *   <li>{@code numFailed(Integer)} - Set the number of failed conversions</li>
+   * </ul>
+   */
+  @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
+  public static class Builder { }
+
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ResponseType.java

@@ -0,0 +1,48 @@
+package ai.docling.serve.api.convert.response;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Defines the response type for document conversion operations.
+ *
+ * <p>Each enumeration value corresponds to a specific response format and determines how
+ * the converted document content is delivered to the client:
+ *
+ * <ul>
+ *   <li>{@link #IN_BODY} - Content is embedded directly in the response body
+ *       ({@link InBodyConvertDocumentResponse})</li>
+ *   <li>{@link #ZIP_ARCHIVE} - Content is packaged and returned as a ZIP archive
+ *       ({@link ZipArchiveConvertDocumentResponse})</li>
+ *   <li>{@link #PRE_SIGNED_URL} - Content is packaged as a ZIP archive and uploaded to the given target URI
+ *   and statistical information is returned.
+ *       ({@link PreSignedUrlConvertDocumentResponse})</li>
+ * </ul>
+ *
+ * @see ConvertDocumentResponse
+ * @see InBodyConvertDocumentResponse
+ * @see ZipArchiveConvertDocumentResponse
+ * @see PreSignedUrlConvertDocumentResponse
+ */
+public enum ResponseType {
+
+  /**
+   * Represents response type - {@link InBodyConvertDocumentResponse}
+   *
+   */
+  @JsonProperty("in_body")
+  IN_BODY,
+
+  /**
+   * Represents response type - {@link ZipArchiveConvertDocumentResponse}
+   *
+   */
+  @JsonProperty("zip_archive")
+  ZIP_ARCHIVE,
+
+  /**
+   * Represents response type - {@link PreSignedUrlConvertDocumentResponse}
+   *
+   */
+  @JsonProperty("presigned_url")
+  PRE_SIGNED_URL
+}