feat!: v1 api with list of sources and target (#249)

Signed-off-by: Michele Dolfi <[email protected]>

Author: dolfim-ibm

README.md

@@ -15,6 +15,9 @@ Running [Docling](https://github.com/docling-project/docling) as an API service.
 - Explore usefule [deployment examples](./docs/deployment.md)
 - And more
 
+ > [!NOTE] Migration to the `v1` API
+> Docling Serve now has a stable v1 API. Read more on the [migration to v1](./docs/v1_migration.md).
+
 ## Getting started
 
 Install the `docling-serve` package and run the server.
@@ -39,7 +42,7 @@ Try it out with a simple conversion:
 
 ```bash
 curl -X 'POST' \
-  'http://localhost:5001/v1alpha/convert/source' \
+  'http://localhost:5001/v1/convert/source' \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -d '{

docling_serve/app.py

@@ -11,6 +11,7 @@
     BackgroundTasks,
     Depends,
     FastAPI,
+    Form,
     HTTPException,
     Query,
     UploadFile,
@@ -32,7 +33,9 @@
     ProgressCallbackRequest,
     ProgressCallbackResponse,
 )
+from docling_jobkit.datamodel.http_inputs import FileSource, HttpSource
 from docling_jobkit.datamodel.task import Task, TaskSource
+from docling_jobkit.datamodel.task_targets import InBodyTarget, TaskTarget, ZipTarget
 from docling_jobkit.orchestrators.base_orchestrator import (
     BaseOrchestrator,
     ProgressInvalid,
@@ -41,9 +44,10 @@
 
 from docling_serve.datamodel.convert import ConvertDocumentsRequestOptions
 from docling_serve.datamodel.requests import (
-    ConvertDocumentFileSourcesRequest,
-    ConvertDocumentHttpSourcesRequest,
     ConvertDocumentsRequest,
+    FileSourceRequest,
+    HttpSourceRequest,
+    TargetName,
 )
 from docling_serve.datamodel.responses import (
     ClearResponse,
@@ -237,20 +241,24 @@ async def _enque_source(
         orchestrator: BaseOrchestrator, conversion_request: ConvertDocumentsRequest
     ) -> Task:
         sources: list[TaskSource] = []
-        if isinstance(conversion_request, ConvertDocumentFileSourcesRequest):
-            sources.extend(conversion_request.file_sources)
-        if isinstance(conversion_request, ConvertDocumentHttpSourcesRequest):
-            sources.extend(conversion_request.http_sources)
+        for s in conversion_request.sources:
+            if isinstance(s, FileSourceRequest):
+                sources.append(FileSource.model_validate(s))
+            elif isinstance(s, HttpSourceRequest):
+                sources.append(HttpSource.model_validate(s))
 
         task = await orchestrator.enqueue(
-            sources=sources, options=conversion_request.options
+            sources=sources,
+            options=conversion_request.options,
+            target=conversion_request.target,
         )
         return task
 
     async def _enque_file(
         orchestrator: BaseOrchestrator,
         files: list[UploadFile],
         options: ConvertDocumentsRequestOptions,
+        target: TaskTarget,
     ) -> Task:
         _log.info(f"Received {len(files)} files for processing.")
 
@@ -262,7 +270,9 @@ async def _enque_file(
             name = file.filename if file.filename else f"file{suffix}.pdf"
             file_sources.append(DocumentStream(name=name, stream=buf))
 
-        task = await orchestrator.enqueue(sources=file_sources, options=options)
+        task = await orchestrator.enqueue(
+            sources=file_sources, options=options, target=target
+        )
         return task
 
     async def _wait_task_complete(orchestrator: BaseOrchestrator, task_id: str) -> bool:
@@ -300,7 +310,7 @@ def api_check() -> HealthCheckResponse:
 
     # Convert a document from URL(s)
     @app.post(
-        "/v1alpha/convert/source",
+        "/v1/convert/source",
         response_model=ConvertDocumentResponse,
         responses={
             200: {
@@ -336,7 +346,7 @@ async def process_url(
 
     # Convert a document from file(s)
     @app.post(
-        "/v1alpha/convert/file",
+        "/v1/convert/file",
         response_model=ConvertDocumentResponse,
         responses={
             200: {
@@ -351,9 +361,11 @@ async def process_file(
         options: Annotated[
             ConvertDocumentsRequestOptions, FormDepends(ConvertDocumentsRequestOptions)
         ],
+        target_type: Annotated[TargetName, Form()] = TargetName.INBODY,
     ):
+        target = InBodyTarget() if target_type == TargetName.INBODY else ZipTarget()
         task = await _enque_file(
-            orchestrator=orchestrator, files=files, options=options
+            orchestrator=orchestrator, files=files, options=options, target=target
         )
         completed = await _wait_task_complete(
             orchestrator=orchestrator, task_id=task.task_id
@@ -374,7 +386,7 @@ async def process_file(
 
     # Convert a document from URL(s) using the async api
     @app.post(
-        "/v1alpha/convert/source/async",
+        "/v1/convert/source/async",
         response_model=TaskStatusResponse,
     )
     async def process_url_async(
@@ -396,7 +408,7 @@ async def process_url_async(
 
     # Convert a document from file(s) using the async api
     @app.post(
-        "/v1alpha/convert/file/async",
+        "/v1/convert/file/async",
         response_model=TaskStatusResponse,
     )
     async def process_file_async(
@@ -406,9 +418,11 @@ async def process_file_async(
         options: Annotated[
             ConvertDocumentsRequestOptions, FormDepends(ConvertDocumentsRequestOptions)
         ],
+        target_type: Annotated[TargetName, Form()] = TargetName.INBODY,
     ):
+        target = InBodyTarget() if target_type == TargetName.INBODY else ZipTarget()
         task = await _enque_file(
-            orchestrator=orchestrator, files=files, options=options
+            orchestrator=orchestrator, files=files, options=options, target=target
         )
         task_queue_position = await orchestrator.get_queue_position(
             task_id=task.task_id
@@ -422,7 +436,7 @@ async def process_file_async(
 
     # Task status poll
     @app.get(
-        "/v1alpha/status/poll/{task_id}",
+        "/v1/status/poll/{task_id}",
         response_model=TaskStatusResponse,
     )
     async def task_status_poll(
@@ -446,7 +460,7 @@ async def task_status_poll(
 
     # Task status websocket
     @app.websocket(
-        "/v1alpha/status/ws/{task_id}",
+        "/v1/status/ws/{task_id}",
     )
     async def task_status_ws(
         websocket: WebSocket,
@@ -510,7 +524,7 @@ async def task_status_ws(
 
     # Task result
     @app.get(
-        "/v1alpha/result/{task_id}",
+        "/v1/result/{task_id}",
         response_model=ConvertDocumentResponse,
         responses={
             200: {
@@ -534,7 +548,7 @@ async def task_result(
 
     # Update task progress
     @app.post(
-        "/v1alpha/callback/task/progress",
+        "/v1/callback/task/progress",
         response_model=ProgressCallbackResponse,
     )
     async def callback_task_progress(
@@ -555,7 +569,7 @@ async def callback_task_progress(
 
     # Offload models
     @app.get(
-        "/v1alpha/clear/converters",
+        "/v1/clear/converters",
         response_model=ClearResponse,
     )
     async def clear_converters(
@@ -566,7 +580,7 @@ async def clear_converters(
 
     # Clean results
     @app.get(
-        "/v1alpha/clear/results",
+        "/v1/clear/results",
         response_model=ClearResponse,
     )
     async def clear_results(

docling_serve/datamodel/requests.py

@@ -1,24 +1,38 @@
-from typing import Union
+import enum
+from typing import Annotated, Literal
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from docling_jobkit.datamodel.http_inputs import FileSource, HttpSource
+from docling_jobkit.datamodel.task_targets import InBodyTarget, TaskTarget, ZipTarget
 
 from docling_serve.datamodel.convert import ConvertDocumentsRequestOptions
 
+## Sources
 
-class DocumentsConvertBase(BaseModel):
-    options: ConvertDocumentsRequestOptions = ConvertDocumentsRequestOptions()
+
+class FileSourceRequest(FileSource):
+    kind: Literal["file"] = "file"
 
 
-class ConvertDocumentHttpSourcesRequest(DocumentsConvertBase):
-    http_sources: list[HttpSource]
+class HttpSourceRequest(HttpSource):
+    kind: Literal["http"] = "http"
 
 
-class ConvertDocumentFileSourcesRequest(DocumentsConvertBase):
-    file_sources: list[FileSource]
+## Multipart targets
+class TargetName(str, enum.Enum):
+    INBODY = InBodyTarget().kind
+    ZIP = ZipTarget().kind
 
 
-ConvertDocumentsRequest = Union[
-    ConvertDocumentFileSourcesRequest, ConvertDocumentHttpSourcesRequest
+## Aliases
+SourceRequestItem = Annotated[
+    FileSourceRequest | HttpSourceRequest, Field(discriminator="kind")
 ]
+
+
+## Complete Source request
+class ConvertDocumentsRequest(BaseModel):
+    options: ConvertDocumentsRequestOptions = ConvertDocumentsRequestOptions()
+    sources: list[SourceRequestItem]
+    target: TaskTarget = InBodyTarget()

docling_serve/gradio_ui.py

@@ -241,7 +241,7 @@ def wait_task_finish(task_id: str, return_as_file: bool):
     while not task_finished:
         try:
             response = httpx.get(
-                f"{get_api_endpoint()}/v1alpha/status/poll/{task_id}?wait=5",
+                f"{get_api_endpoint()}/v1/status/poll/{task_id}?wait=5",
                 verify=ssl_ctx,
                 timeout=15,
             )
@@ -264,7 +264,7 @@ def wait_task_finish(task_id: str, return_as_file: bool):
     if conversion_sucess:
         try:
             response = httpx.get(
-                f"{get_api_endpoint()}/v1alpha/result/{task_id}",
+                f"{get_api_endpoint()}/v1/result/{task_id}",
                 timeout=15,
                 verify=ssl_ctx,
             )
@@ -296,8 +296,11 @@ def process_url(
     do_picture_classification,
     do_picture_description,
 ):
+    target = {"kind": "zip" if return_as_file else "inbody"}
     parameters = {
-        "http_sources": [{"url": source} for source in input_sources.split(",")],
+        "sources": [
+            {"kind": "http", "url": source} for source in input_sources.split(",")
+        ],
         "options": {
             "to_formats": to_formats,
             "image_export_mode": image_export_mode,
@@ -309,24 +312,24 @@ def process_url(
             "pdf_backend": pdf_backend,
             "table_mode": table_mode,
             "abort_on_error": abort_on_error,
-            "return_as_file": return_as_file,
             "do_code_enrichment": do_code_enrichment,
             "do_formula_enrichment": do_formula_enrichment,
             "do_picture_classification": do_picture_classification,
             "do_picture_description": do_picture_description,
         },
+        "target": target,
     }
     if (
-        not parameters["http_sources"]
-        or len(parameters["http_sources"]) == 0
-        or parameters["http_sources"][0]["url"] == ""
+        not parameters["sources"]
+        or len(parameters["sources"]) == 0
+        or parameters["sources"][0]["url"] == ""
     ):
         logger.error("No input sources provided.")
         raise gr.Error("No input sources provided.", print_exception=False)
     try:
         ssl_ctx = get_ssl_context()
         response = httpx.post(
-            f"{get_api_endpoint()}/v1alpha/convert/source/async",
+            f"{get_api_endpoint()}/v1/convert/source/async",
             json=parameters,
             verify=ssl_ctx,
             timeout=60,
@@ -372,11 +375,13 @@ def process_file(
         logger.error("No files provided.")
         raise gr.Error("No files provided.", print_exception=False)
     files_data = [
-        {"base64_string": file_to_base64(file), "filename": file.name} for file in files
+        {"kind": "file", "base64_string": file_to_base64(file), "filename": file.name}
+        for file in files
     ]
+    target = {"kind": "zip" if return_as_file else "inbody"}
 
     parameters = {
-        "file_sources": files_data,
+        "sources": files_data,
         "options": {
             "to_formats": to_formats,
             "image_export_mode": image_export_mode,
@@ -394,12 +399,13 @@ def process_file(
             "do_picture_classification": do_picture_classification,
             "do_picture_description": do_picture_description,
         },
+        "target": target,
     }
 
     try:
         ssl_ctx = get_ssl_context()
         response = httpx.post(
-            f"{get_api_endpoint()}/v1alpha/convert/source/async",
+            f"{get_api_endpoint()}/v1/convert/source/async",
             json=parameters,
             verify=ssl_ctx,
             timeout=60,

docling_serve/response_preparation.py

@@ -15,6 +15,7 @@
 from docling_core.types.doc import ImageRefMode
 from docling_jobkit.datamodel.convert import ConvertDocumentsOptions
 from docling_jobkit.datamodel.task import Task
+from docling_jobkit.datamodel.task_targets import InBodyTarget, TaskTarget
 from docling_jobkit.orchestrators.base_orchestrator import (
     BaseOrchestrator,
 )
@@ -139,6 +140,7 @@ def _export_documents_as_files(
 
 def process_results(
     conversion_options: ConvertDocumentsOptions,
+    target: TaskTarget,
     conv_results: Iterable[ConversionResult],
     work_dir: Path,
 ) -> Union[ConvertDocumentResponse, FileResponse]:
@@ -175,7 +177,7 @@ def process_results(
     export_doctags = OutputFormat.DOCTAGS in conversion_options.to_formats
 
     # Only 1 document was processed, and we are not returning it as a file
-    if len(conv_results) == 1 and not conversion_options.return_as_file:
+    if len(conv_results) == 1 and isinstance(target, InBodyTarget):
         conv_res = conv_results[0]
         document = _export_document_as_content(
             conv_res,
@@ -252,6 +254,7 @@ async def prepare_response(
     work_dir = get_scratch() / task.task_id
     response = process_results(
         conversion_options=task.options,
+        target=task.target,
         conv_results=task.results,
         work_dir=work_dir,
     )

docs/README.md

@@ -6,3 +6,4 @@ This documentation pages explore the webserver configurations, runtime options,
 - [Advance usage](./usage.md)
 - [Deployment](./deployment.md)
 - [Development](./development.md)
+- [`v1` migration](./v1_migration.md)

docs/configuration.md

@@ -76,6 +76,6 @@ The following table describes the options to configure the Docling Serve KFP eng
 | `DOCLING_SERVE_ENG_KFP_ENDPOINT` |  | Must be set to the Kubeflow Pipeline endpoint. When using the in-cluster deployment, make sure to use the cluster endpoint, e.g. `https://NAME.NAMESPACE.svc.cluster.local:8888`  |
 | `DOCLING_SERVE_ENG_KFP_TOKEN` |  | The authentication token for KFP. For in-cluster deployment, the app will load automatically the token of the ServiceAccount. |
 | `DOCLING_SERVE_ENG_KFP_CA_CERT_PATH` |  | Path to the CA certificates for the KFP endpoint. For in-cluster deployment, the app will load automatically the internal CA. |
-| `DOCLING_SERVE_ENG_KFP_SELF_CALLBACK_ENDPOINT` |  | If set, it enables internal callbacks providing status update of the KFP job. Usually something like `https://NAME.NAMESPACE.svc.cluster.local:5001/v1alpha/callback/task/progress`. |
+| `DOCLING_SERVE_ENG_KFP_SELF_CALLBACK_ENDPOINT` |  | If set, it enables internal callbacks providing status update of the KFP job. Usually something like `https://NAME.NAMESPACE.svc.cluster.local:5001/v1/callback/task/progress`. |
 | `DOCLING_SERVE_ENG_KFP_SELF_CALLBACK_TOKEN_PATH` |  | The token used for authenticating the progress callback. For cluster-internal workloads, use `/run/secrets/kubernetes.io/serviceaccount/token`. |
 | `DOCLING_SERVE_ENG_KFP_SELF_CALLBACK_CA_CERT_PATH` |  | The CA certificate for the progress callback. For cluster-inetrnal workloads, use `/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt`. |