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					212, 219-226, 231-232, 321-322, 332-334, 357-358, 371-372, 375-390, 428-429, 439-441, 454-456, 565, 588-589
Project Total

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

[davidsbatista]

This execption DoclingServeConversionError raised on timeout ends up being caught by the same except block in run() / run_async() that also handles ordinary conversion failures:

If a job exceeds job_timeout (default 600s), the caller silently gets an empty documents list after waiting 10 minutes — indistinguishable from "file had no content". A timeout feels like a different signal from a conversion failure.

One option would be a dedicated subclass:

class DoclingServeTimeoutError(DoclingServeConversionError):
    """Raised when a job exceeds job_timeout."""

That way callers can catch it separately, and you could re-raise it in run() or at least use a more specific log message.

Same for the run_async()

[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"