feat: Add file-based operations for conversion and chunking (#229)

- Introduced support for file-based conversion and chunking workflows.
- Added synchronous and asynchronous methods for handling file paths in API and client layers.
- Enhanced error handling and validation for file-based operations.
- Updated tests to cover new file-based use cases, including edge cases and null checks.



Fixes #227

Signed-off-by: Eric Deandrea <[email protected]>

Author: edeandrea

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

@@ -1,10 +1,16 @@
 package ai.docling.serve.api;
 
-import java.util.concurrent.CompletableFuture;
+import java.nio.file.Path;
+import java.util.Optional;
+import java.util.concurrent.CompletionStage;
+
+import org.jspecify.annotations.Nullable;
 
 import ai.docling.serve.api.chunk.request.HierarchicalChunkDocumentRequest;
 import ai.docling.serve.api.chunk.request.HybridChunkDocumentRequest;
 import ai.docling.serve.api.chunk.response.ChunkDocumentResponse;
+import ai.docling.serve.api.util.FileUtils;
+import ai.docling.serve.api.util.ValidationUtils;
 
 /**
  * Represents the Docling Serve Chunk API, providing methods for processing document sources
@@ -19,21 +25,120 @@ public interface DoclingServeChunkApi {
   ChunkDocumentResponse chunkSourceWithHierarchicalChunker(HierarchicalChunkDocumentRequest request);
 
   /**
-   * Converts and chunks the provided document source(s) into a processed document based on the specified options
-   * and using a hybrid chunker for splitting the document into smaller chunks.
+   * Processes and chunks the specified files into smaller, structured pieces
+   * using a hierarchical chunker. This method internally delegates the processing
+   * to another overloaded method with default options for the hierarchical chunker.
+   *
+   * @param files the files to be processed and chunked using the hierarchical chunker
+   * @return a {@link ChunkDocumentResponse} containing the processed chunks, optionally the
+   *         converted documents, and associated metadata
+   */
+  default ChunkDocumentResponse chunkFilesWithHierarchicalChunker(Path... files) {
+    return chunkFilesWithHierarchicalChunker(null, files);
+  }
+
+  /**
+   * Processes and chunks the specified files into smaller, structured pieces
+   * using a hierarchical chunker. This method utilizes a provided hierarchical
+   * chunk request, applying additional configurations if needed during the
+   * creation of the chunking request.
+   *
+   * @param request the request containing configurations and options for hierarchical
+   *                chunking. It may include settings for conversion, chunking parameters,
+   *                and optional output specifications. Can be null to use default options.
+   * @param files   the files to be processed and chunked using the hierarchical chunker.
+   * @return a {@link ChunkDocumentResponse} containing the processed chunks, optionally the
+   *         converted documents, and associated metadata.
+   */
+  default ChunkDocumentResponse chunkFilesWithHierarchicalChunker(@Nullable HierarchicalChunkDocumentRequest request, Path... files) {
+    return chunkSourceWithHierarchicalChunker(createHierarchicalChunkRequest(request, files));
+  }
+
+  /**
+   * Processes and chunks the provided document source(s) into smaller documents
+   * using a hybrid chunking strategy. The method utilizes the specified hybrid
+   * chunker options to split and process the input request.
+   *
+   * @param request the request containing the document source(s), conversion options, hybrid
+   *                chunker configurations, and optional specifications for output targets
+   * @return a {@link ChunkDocumentResponse} containing the processed chunks, optionally the
+   *         converted document, and other relevant metadata
    */
   ChunkDocumentResponse chunkSourceWithHybridChunker(HybridChunkDocumentRequest request);
 
+  /**
+   * Processes and chunks the specified files into smaller, structured pieces
+   * using a hybrid chunking strategy. This method delegates the processing
+   * to another overloaded method with default options for the hybrid chunker.
+   *
+   * @param files the files to be processed and chunked using the hybrid chunker
+   * @return a {@link ChunkDocumentResponse} containing the processed chunks,
+   *         optionally the converted documents, and associated metadata
+   */
+  default ChunkDocumentResponse chunkFilesWithHybridChunker(Path... files) {
+    return chunkFilesWithHybridChunker(null, files);
+  }
+
+  /**
+   * Processes and chunks the specified files into smaller, structured pieces
+   * using a hybrid chunking strategy. The method converts the input files into
+   * a hybrid chunk request and processes them to generate a structured representation
+   * of the content.
+   *
+   * @param request the request containing configurations for processing, including
+   *                conversion options, hybrid chunking parameters, and optional
+   *                specifications for output targets. Can be null to use default options.
+   * @param files   the files to be processed and chunked using the hybrid chunking strategy.
+   * @return a {@code ChunkDocumentResponse} containing the processed chunks, optionally the
+   *         converted documents, and associated metadata.
+   */
+  default ChunkDocumentResponse chunkFilesWithHybridChunker(@Nullable HybridChunkDocumentRequest request, Path... files) {
+    return chunkSourceWithHybridChunker(createHybridChunkRequest(request, files));
+  }
+
   /**
    * Asynchronously processes the provided document source(s) by converting and chunking them
    * into smaller documents using the hierarchical chunker. This operation allows for handling
    * large document processing tasks without blocking the caller thread.
    *
    * @param request the request containing the document source(s) and options for hierarchical chunking
-   * @return a CompletableFuture that resolves to a {@link ChunkDocumentResponse}, which contains
+   * @return a {@link CompletionStage} that resolves to a {@link ChunkDocumentResponse}, which contains
    *         the processed chunks, optionally the converted document, and processing metadata
    */
-  CompletableFuture<ChunkDocumentResponse> chunkSourceWithHierarchicalChunkerAsync(HierarchicalChunkDocumentRequest request);
+  CompletionStage<ChunkDocumentResponse> chunkSourceWithHierarchicalChunkerAsync(HierarchicalChunkDocumentRequest request);
+
+  /**
+   * Asynchronously processes and chunks the specified files into smaller, structured pieces
+   * using a hierarchical chunker. This method delegates the processing to another overloaded
+   * method with default options for the hierarchical chunker, leveraging non-blocking
+   * asynchronous execution.
+   *
+   * @param files the files to be processed and chunked using the hierarchical chunker
+   * @return a {@link CompletionStage} resolving to a {@link ChunkDocumentResponse}, which
+   *         includes the processed chunks, optionally the converted documents, and associated
+   *         metadata
+   */
+  default CompletionStage<ChunkDocumentResponse> chunkFilesWithHierarchicalChunkerAsync(Path... files) {
+    return chunkFilesWithHierarchicalChunkerAsync(null, files);
+  }
+
+  /**
+   * Asynchronously processes and chunks the specified files into smaller, structured pieces
+   * using a hierarchical chunker. This method allows for non-blocking execution by delegating
+   * the processing to an underlying method that handles hierarchical chunking configurations
+   * and file chunking.
+   *
+   * @param request the request object containing configurations, options for hierarchical
+   *                chunking, and optional specifications for output targets. Can be null
+   *                to use default options for processing.
+   * @param files   the files to be processed and chunked using the hierarchical chunker.
+   * @return a {@link CompletionStage} that resolves to a {@link ChunkDocumentResponse},
+   *         which includes the processed chunks, optionally the converted documents,
+   *         and associated metadata.
+   */
+  default CompletionStage<ChunkDocumentResponse> chunkFilesWithHierarchicalChunkerAsync(@Nullable HierarchicalChunkDocumentRequest request, Path... files) {
+    return chunkSourceWithHierarchicalChunkerAsync(createHierarchicalChunkRequest(request, files));
+  }
 
   /**
    * Asynchronously processes the provided document source(s) by converting and chunking them
@@ -42,8 +147,60 @@ public interface DoclingServeChunkApi {
    *
    * @param request the request containing the document source(s), options for conversion,
    *                hybrid chunking parameters, and optional specifications for output targets
-   * @return a CompletableFuture that resolves to a {@link ChunkDocumentResponse}, which includes
+   * @return a {@link CompletionStage} that resolves to a {@link ChunkDocumentResponse}, which includes
    *         the processed chunks, optionally the converted document, and relevant processing metadata
    */
-  CompletableFuture<ChunkDocumentResponse> chunkSourceWithHybridChunkerAsync(HybridChunkDocumentRequest request);
+  CompletionStage<ChunkDocumentResponse> chunkSourceWithHybridChunkerAsync(HybridChunkDocumentRequest request);
+
+  /**
+   * Asynchronously processes and chunks the provided files using a hybrid chunking strategy.
+   *
+   * @param files An array of file paths to be processed and chunked. Each path should represent
+   *              a valid file location.
+   * @return A CompletionStage that, when completed, holds a ChunkDocumentResponse containing
+   *         the results of the chunking operation.
+   */
+  default CompletionStage<ChunkDocumentResponse> chunkFilesWithHybridChunkerAsync(Path... files) {
+    return chunkFilesWithHybridChunkerAsync(null, files);
+  }
+
+  /**
+   * Asynchronously processes and chunks the given files using a hybrid chunking mechanism.
+   *
+   * @param request An optional {@code HybridChunkDocumentRequest} containing configuration details for chunking.
+   *                If {@code null}, default settings will be applied.
+   * @param files   A varargs array of {@code Path} objects representing the files to be chunked.
+   *                Must not be null or empty.
+   * @return A {@code CompletionStage<ChunkDocumentResponse>} that completes with the resulting
+   *         {@code ChunkDocumentResponse} once the chunking operation is finished.
+   */
+  default CompletionStage<ChunkDocumentResponse> chunkFilesWithHybridChunkerAsync(@Nullable HybridChunkDocumentRequest request, Path... files) {
+    return chunkSourceWithHybridChunkerAsync(createHybridChunkRequest(request, files));
+  }
+
+  private HierarchicalChunkDocumentRequest createHierarchicalChunkRequest(@Nullable HierarchicalChunkDocumentRequest request, Path... files) {
+    ValidationUtils.ensureNotEmpty(files, "files");
+
+    var builder = Optional.ofNullable(request)
+        .map(HierarchicalChunkDocumentRequest::toBuilder)
+        .orElseGet(HierarchicalChunkDocumentRequest::builder);
+
+    FileUtils.createFileSources(files)
+        .forEach(builder::source);
+
+    return builder.build();
+  }
+
+  private HybridChunkDocumentRequest createHybridChunkRequest(@Nullable HybridChunkDocumentRequest request, Path... files) {
+    ValidationUtils.ensureNotEmpty(files, "files");
+
+    var builder = Optional.ofNullable(request)
+        .map(HybridChunkDocumentRequest::toBuilder)
+        .orElseGet(HybridChunkDocumentRequest::builder);
+
+    FileUtils.createFileSources(files)
+        .forEach(builder::source);
+
+    return builder.build();
+  }
 }

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

@@ -1,9 +1,15 @@
 package ai.docling.serve.api;
 
-import java.util.concurrent.CompletableFuture;
+import java.nio.file.Path;
+import java.util.Optional;
+import java.util.concurrent.CompletionStage;
+
+import org.jspecify.annotations.Nullable;
 
 import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
 import ai.docling.serve.api.convert.response.ConvertDocumentResponse;
+import ai.docling.serve.api.util.FileUtils;
+import ai.docling.serve.api.util.ValidationUtils;
 
 /**
  * Interface representing the Docling Serve Convert API.
@@ -19,9 +25,34 @@ public interface DoclingServeConvertApi {
    */
   ConvertDocumentResponse convertSource(ConvertDocumentRequest request);
 
+  /**
+   * Converts the specified files into a processed document using default options.
+   * This is a convenience method that delegates to {@link #convertFiles(ConvertDocumentRequest, Path...)}
+   * with a null request.
+   *
+   * @param files an array of {@link Path} objects representing the file paths to be converted
+   * @return a {@link ConvertDocumentResponse} containing the processed document data, metadata, and any errors
+   */
+  default ConvertDocumentResponse convertFiles(Path... files) {
+    return convertFiles(null, files);
+  }
+
+  /**
+   * Converts the specified files into a processed document based on the options provided in the request.
+   * If the request is null, default conversion options are applied.
+   *
+   * @param request an optional {@link ConvertDocumentRequest} specifying conversion settings and parameters
+   * @param files an array of {@link Path} objects representing the file paths to be converted
+   * @return a {@link ConvertDocumentResponse} containing the processed document data, any errors encountered,
+   *         and additional processing metadata
+   */
+  default ConvertDocumentResponse convertFiles(@Nullable ConvertDocumentRequest request, Path... files) {
+    return convertSource(createRequest(request, files));
+  }
+
   /**
    * Initiates an asynchronous conversion of the provided document source(s) and returns a
-   * {@link CompletableFuture} that completes when the conversion is done.
+   * {@link CompletionStage} that completes when the conversion is done.
    *
    * <p>This method starts the conversion, polls the status in the background, and completes
    * the future with the result when the conversion finishes.
@@ -35,9 +66,51 @@ public interface DoclingServeConvertApi {
    * }</pre>
    *
    * @param request the {@link ConvertDocumentRequest} containing the source(s) and conversion options.
-   * @return a {@link CompletableFuture} that completes with the {@link ConvertDocumentResponse}
+   * @return a {@link CompletionStage} that completes with the {@link ConvertDocumentResponse}
    *         when the conversion is finished, or completes exceptionally if the conversion fails
    *         or times out.
    */
-  CompletableFuture<ConvertDocumentResponse> convertSourceAsync(ConvertDocumentRequest request);
+  CompletionStage<ConvertDocumentResponse> convertSourceAsync(ConvertDocumentRequest request);
+
+  /**
+   * Initiates an asynchronous conversion of the provided files into a processed document
+   * using default conversion options.
+   *
+   * @param files an array of {@link Path} objects representing the file paths to be converted
+   * @return a {@link CompletionStage} that completes with the {@link ConvertDocumentResponse}
+   *         when the conversion finishes, or completes exceptionally if the conversion fails
+   *         or times out
+   */
+  default CompletionStage<ConvertDocumentResponse> convertFilesAsync(Path... files) {
+    return convertFilesAsync(null, files);
+  }
+
+  /**
+   * Initiates an asynchronous conversion of the specified files into a processed document
+   * using the provided conversion request options. If the request is null, default conversion
+   * options are applied.
+   *
+   * @param request an optional {@link ConvertDocumentRequest} containing conversion settings
+   *                and parameters, or null to use default options
+   * @param files   an array of {@link Path} objects representing the file paths to be converted
+   * @return a {@link CompletionStage} that completes with the {@link ConvertDocumentResponse}
+   *         when the conversion finishes, or completes exceptionally if the conversion fails
+   *         or times out
+   */
+  default CompletionStage<ConvertDocumentResponse> convertFilesAsync(@Nullable ConvertDocumentRequest request, Path... files) {
+    return convertSourceAsync(createRequest(request, files));
+  }
+
+  private ConvertDocumentRequest createRequest(@Nullable ConvertDocumentRequest request, Path... files) {
+    ValidationUtils.ensureNotEmpty(files, "files");
+
+    var builder = Optional.ofNullable(request)
+        .map(ConvertDocumentRequest::toBuilder)
+        .orElseGet(ConvertDocumentRequest::builder);
+
+    FileUtils.createFileSources(files)
+        .forEach(builder::source);
+
+    return builder.build();
+  }
 }