feat: add async job mode to Docling Serve converter

[2830500285]

Summary

• Add an async job mode for DoclingServeConverter that submits conversions to Docling Serve's async endpoints and polls until completion.
• Support async jobs for both URL sources and uploaded file/ByteStream sources.
• Preserve the existing synchronous mode as the default and cover serialization, failure handling, and sync/async execution paths with tests.

Closes #3345

Validation

• SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 uvx hatch run fmt-check src/haystack_integrations/components/converters/docling_serve/converter.py src/haystack_integrations/components/converters/docling_serve/init.py tests/test_converter.py
• SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 uvx hatch run test:unit tests/test_converter.py
• SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 uvx hatch run test:types

[github-actions]

Coverage report (docling_serve)

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
integrations/docling_serve/src/haystack_integrations/components/converters/docling_serve
converter.py					218, 237-238
Project Total

This report was generated by python-coverage-comment-action

[davidsbatista]

Suggested change

	Maximum server-side long-poll wait in seconds when `mode="async"`.
	Controls both the server-side long-poll wait (?wait= parameter) and the maximum local sleep between polls. A higher value reduces round-trips; a lower value increases polling frequency.

[davidsbatista]

those are only used in async, so we can do:

if self.mode == ConversionMode.ASYNC:
      if poll_interval <= 0:
          msg = "poll_interval must be greater than 0."
          raise ValueError(msg)
      if job_timeout <= 0:
          msg = "job_timeout must be greater than 0."
          raise ValueError(msg)

[davidsbatista]

This is a pre-existing issue, not introduced by this PR, but worth fixing.

The sync endpoints (_post_file, _post_url) return the raw response JSON without checking the status field in the body. This means if DoclingServe returns a 200 OK with {"status": "failure", "errors": [...]}, the error details are silently discarded — the code falls through to _extract_content, gets None, and logs "No content returned for source" with no indication of why.

The async job path handles this correctly via _raise_for_failed_conversion in _fetch_job_result.

Let's apply the same check to _post_file and _post_url to make the behaviour consistent.

[davidsbatista]

There's a test for run_async() with ASYNC mode and a URL source, but no equivalent for a file source.

Could you add a test that verifies run_async() with mode=ASYNC and a file path hits /v1/convert/file/async and returns the converted document?

[davidsbatista]

Could you add a test for the timeout path?

When job_timeout is exceeded, DoclingServeConversionError is raised and caught — the source should be skipped with a warning containing "Timed out".

[davidsbatista]

Also a test for the "skipped" status?

A job can complete with task_status: "success" but the conversion result can still have status: "skipped"

[davidsbatista]

Hi @2830500285!

Is the PR already ready for a second review? What were the changes did you introduced you want me to look into?

[2830500285]

Hi @davidsbatista, yes, this is ready for a second review.

I addressed the review feedback in 601b473:

• added DoclingServeTimeoutError and a specific timeout warning path in run() / run_async()
• clarified poll_interval docs
• validate poll_interval and job_timeout only when mode="async"
• check DoclingServe response body status for the sync/direct endpoints as well
• added tests for async file job conversions, timeout handling, skipped conversion results, and direct endpoint failure details

CI is green and the coverage report improved to 96.7% overall / 98.59% PR coverage.

[davidsbatista]

Looks good!