feat(api): add PreSignedUrlConvertResponse for PresignedUrlTarget

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

@@ -0,0 +1,73 @@
+package ai.docling.serve.api.convert.response;
+
+import java.net.URI;
+import java.time.Instant;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Represents a reference to a single output artifact returned as a presigned URL.
+ *
+ * <p>Serialization uses {@link JsonInclude.Include#NON_EMPTY}, so nulls and empty
+ * fields are omitted from JSON output.</p>
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = ArtifactRef.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class ArtifactRef {
+
+  /**
+   * Export format of the artifact.
+   *
+   * @param artifactType the artifact type
+   * @return the artifact type
+   */
+  @JsonProperty("artifact_type")
+  private ArtifactType artifactType;
+
+  /**
+   * MIME type of the artifact content.
+   *
+   * @param mimeType the MIME type
+   * @return the MIME type
+   */
+  @JsonProperty("mime_type")
+  private String mimeType;
+
+  /**
+   * Presigned URL used to download the artifact.
+   *
+   * @param uri the presigned URL
+   * @return the presigned URL
+   */
+  @JsonProperty("uri")
+  private URI uri;
+
+  /**
+   * Instant at which the presigned URL signature stops being valid.
+   *
+   * @param urlExpiresAt the expiry timestamp
+   * @return the expiry timestamp
+   */
+  @JsonProperty("url_expires_at")
+  private Instant urlExpiresAt;
+
+  /**
+   * Builder for creating {@link ArtifactRef} instances.
+   * Generated by Lombok's {@code @Builder} annotation.
+   *
+   * <p>Builder methods:
+   * <ul>
+   *   <li>{@code artifactType(ArtifactType)} - Set the artifact type</li>
+   *   <li>{@code mimeType(String)} - Set the MIME type</li>
+   *   <li>{@code uri(URI)} - Set the presigned URL</li>
+   *   <li>{@code urlExpiresAt(Instant)} - Set the expiry timestamp</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/ArtifactType.java

@@ -0,0 +1,25 @@
+package ai.docling.serve.api.convert.response;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Represents the output format of a converted-document artifact.
+ * Each value is mapped to a specific JSON property for serialization and deserialization.
+ *
+ * <ul>
+ *   <li>{@code JSON}: Serialized {@code DoclingDocument} JSON.</li>
+ *   <li>{@code HTML}: HTML rendering of the document.</li>
+ *   <li>{@code MARKDOWN}: Markdown rendering of the document.</li>
+ *   <li>{@code TEXT}: Plain-text rendering of the document.</li>
+ *   <li>{@code DOCTAGS}: DocTags rendering of the document.</li>
+ *   <li>{@code RESOURCE_BUNDLE}: ZIP archive containing extracted images and supporting resources.</li>
+ * </ul>
+ */
+public enum ArtifactType {
+  @JsonProperty("json") JSON,
+  @JsonProperty("html") HTML,
+  @JsonProperty("markdown") MARKDOWN,
+  @JsonProperty("text") TEXT,
+  @JsonProperty("doctags") DOCTAGS,
+  @JsonProperty("resource_bundle") RESOURCE_BUNDLE;
+}

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

@@ -0,0 +1,25 @@
+package ai.docling.serve.api.convert.response;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Represents the possible conversion outcomes for a document.
+ * Each status is mapped to a specific JSON property for serialization and deserialization.
+ *
+ * <ul>
+ *   <li>{@code PENDING}: Indicates that the conversion has not yet started.</li>
+ *   <li>{@code STARTED}: Indicates that the conversion is currently in progress.</li>
+ *   <li>{@code SUCCESS}: Indicates that all pages of the document were converted.</li>
+ *   <li>{@code PARTIAL_SUCCESS}: Indicates that some pages were converted and others failed.</li>
+ *   <li>{@code FAILURE}: Indicates that the document could not be converted.</li>
+ *   <li>{@code SKIPPED}: Indicates that the document was rejected at admission.</li>
+ * </ul>
+ */
+public enum ConversionStatus {
+  @JsonProperty("pending") PENDING,
+  @JsonProperty("started") STARTED,
+  @JsonProperty("success") SUCCESS,
+  @JsonProperty("partial_success") PARTIAL_SUCCESS,
+  @JsonProperty("failure") FAILURE,
+  @JsonProperty("skipped") SKIPPED;
+}

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

@@ -18,10 +18,11 @@
 @JsonSubTypes({
     @JsonSubTypes.Type(InBodyConvertDocumentResponse.class),
     @JsonSubTypes.Type(PreSignedUrlConvertDocumentResponse.class),
+    @JsonSubTypes.Type(PreSignedUrlConvertResponse.class),
     @JsonSubTypes.Type(ZipArchiveConvertDocumentResponse.class)
 })
 public abstract sealed class ConvertDocumentResponse permits InBodyConvertDocumentResponse, PreSignedUrlConvertDocumentResponse,
-    ZipArchiveConvertDocumentResponse {
+    PreSignedUrlConvertResponse, ZipArchiveConvertDocumentResponse {
   /**
    * Type of response
    *

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

@@ -0,0 +1,114 @@
+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;
+
+/**
+ * Represents the conversion outcome and artifact references for a single source document.
+ *
+ * <p>Serialization uses {@link JsonInclude.Include#NON_EMPTY}, so nulls and empty
+ * collections are omitted from JSON output.</p>
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = DocumentArtifactItem.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class DocumentArtifactItem {
+
+  /**
+   * Zero-based index of the source document within the originating task.
+   *
+   * @param sourceIndex the source index
+   * @return the source index
+   */
+  @JsonProperty("source_index")
+  private Integer sourceIndex;
+
+  /**
+   * Canonical identifier of the source document.
+   *
+   * @param sourceUri the source URI
+   * @return the source URI
+   */
+  @JsonProperty("source_uri")
+  private String sourceUri;
+
+  /**
+   * Filename used as the stem of each output artifact.
+   *
+   * @param filename the source filename
+   * @return the source filename
+   */
+  @JsonProperty("filename")
+  private String filename;
+
+  /**
+   * Terminal conversion outcome for this document.
+   *
+   * @param status the conversion status
+   * @return the conversion status
+   */
+  @JsonProperty("status")
+  private ConversionStatus status;
+
+  /**
+   * Errors encountered while converting this document.
+   *
+   * @param errors the list of errors
+   * @return the list of errors
+   */
+  @JsonProperty("errors")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private List<ErrorItem> errors;
+
+  /**
+   * Per-stage timing breakdown keyed by stage name.
+   *
+   * @param timings the timings map
+   * @return the timings map
+   */
+  @JsonProperty("timings")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private Map<String, ProfilingItem> timings;
+
+  /**
+   * Presigned URLs for each requested output format.
+   *
+   * @param artifacts the list of artifact references
+   * @return the list of artifact references
+   */
+  @JsonProperty("artifacts")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private List<ArtifactRef> artifacts;
+
+  /**
+   * Builder for creating {@link DocumentArtifactItem} instances.
+   * Generated by Lombok's {@code @Builder} annotation.
+   *
+   * <p>Builder methods:
+   * <ul>
+   *   <li>{@code sourceIndex(Integer)} - Set the source index</li>
+   *   <li>{@code sourceUri(String)} - Set the source URI</li>
+   *   <li>{@code filename(String)} - Set the source filename</li>
+   *   <li>{@code status(ConversionStatus)} - Set the conversion status</li>
+   *   <li>{@code errors(List<ErrorItem>)} - Set the list of errors</li>
+   *   <li>{@code error(ErrorItem)} - Add a single error (use with @Singular)</li>
+   *   <li>{@code timings(Map<String, ProfilingItem>)} - Set the timings map</li>
+   *   <li>{@code timing(String, ProfilingItem)} - Add a single timing entry (use with @Singular)</li>
+   *   <li>{@code artifacts(List<ArtifactRef>)} - Set the list of artifact references</li>
+   *   <li>{@code artifact(ArtifactRef)} - Add a single artifact reference (use with @Singular)</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/PreSignedUrlConvertResponse.java

@@ -0,0 +1,116 @@
+package ai.docling.serve.api.convert.response;
+
+import java.util.List;
+
+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 document conversions that target server-managed presigned URLs.
+ *
+ * <p>This response type is returned when the conversion request specifies a
+ * {@link ai.docling.serve.api.convert.request.target.PresignedUrlTarget}. Each
+ * source document is represented by a {@link DocumentArtifactItem} in
+ * {@link #getDocuments() documents} which carries its conversion outcome and
+ * the list of presigned URLs the server produced for the requested output
+ * formats.</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#PRE_SIGNED_URL_RESPONSE
+ * @see ai.docling.serve.api.convert.request.target.PresignedUrlTarget
+ * @see DocumentArtifactItem
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = PreSignedUrlConvertResponse.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public final class PreSignedUrlConvertResponse 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 numConverted 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 partial successes.
+   *
+   * @param numPartiallySucceeded the number of partial successes
+   * @return the number of partial successes
+   */
+  @JsonProperty("num_partially_succeeded")
+  private Integer numPartiallySucceeded;
+
+  /**
+   * Number of failed conversions.
+   *
+   * @param numFailed the number of failed conversions
+   * @return the number of failed conversions
+   */
+  @JsonProperty("num_failed")
+  private Integer numFailed;
+
+  /**
+   * Per-source conversion outcomes and presigned artifact URLs.
+   *
+   * @param documents the list of per-source artifact items
+   * @return the list of per-source artifact items
+   */
+  @JsonProperty("documents")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private List<DocumentArtifactItem> documents;
+
+  @Override
+  @lombok.ToString.Include
+  public ResponseType getResponseType() {
+    return ResponseType.PRE_SIGNED_URL_RESPONSE;
+  }
+
+  /**
+   * Builder for creating {@link PreSignedUrlConvertResponse} 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 numPartiallySucceeded(Integer)} - Set the number of partial successes</li>
+   *   <li>{@code numFailed(Integer)} - Set the number of failed conversions</li>
+   *   <li>{@code documents(List<DocumentArtifactItem>)} - Set the list of per-source artifact items</li>
+   *   <li>{@code document(DocumentArtifactItem)} - Add a single per-source artifact item (use with @Singular)</li>
+   * </ul>
+   */
+  @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
+  public static class Builder { }
+
+}