feat(file-processors): add async/fallback support to docling-serve

[sahana-sreeram]

What does this PR do?

Adds async API support to the remote::docling-serve file processor with automatic fallback to sync endpoints.

Problem: The sync API (/v1/convert/file) blocks for the entire processing duration, so larger PDFs under concurrent load
can exceed HTTP timeouts. The sync workflow is also incompatible with IBM
Docling SaaS, which only exposes async endpoints.

Solution: Implement the async submit/poll/result pattern (/v1/convert/file/async → GET /status/poll/{task_id} → GET /result/{task_id}) with automatic fallback to sync if async fails. The docling team confirmed async endpoints are
available on local docling-serve and SaaS.

• mode="async" (default): use async endpoints, fall back to sync on failure
• mode="sync": use sync endpoints only (manual fallback)
• mode="auto": detect server capabilities and choose

The async workflow eliminates timeout issues and enables SaaS compatibility. Fallback
ensures resilience when async endpoints are unavailable.
Will need to rebase after #5627 (async request scheduler) merges.

Test Plan

Validated async functionality using both unit tests and integration testing against a local Docling Serve instance.

Unit Tests

All existing tests pass plus 4 new tests covering async behavior:

uv run pytest tests/unit/providers/file_processor/test_docling_serve.py -v

Results:
tests/unit/providers/file_processor/test_docling_serve.py::TestDoclingServeFileProcessor::test_async_mode_calls_async_endpo
int PASSED
tests/unit/providers/file_processor/test_docling_serve.py::TestDoclingServeFileProcessor::test_sync_mode_skips_async_endpoi
nt PASSED
tests/unit/providers/file_processor/test_docling_serve.py::TestDoclingServeFileProcessor::test_fallback_from_async_to_sync
PASSED
tests/unit/providers/file_processor/test_docling_serve.py::TestDoclingServeFileProcessor::test_auto_mode_detects_async_supp
ort PASSED
...
============================== 23 passed in 0.27s ==============================

Integration Testing

Tested against local Docling Serve (docker run -p 5001:5001 quay.io/docling-project/docling-serve) with a real PDF (86
pages, 63MB).

Test 1: Async mode works end-to-end

config = DoclingServeFileProcessorConfig(
    base_url="http://localhost:5001/v1",
    mode="async"  # default
)
processor = DoclingServeFileProcessor(config=config, files_api=files_api)
result = await processor.process_file(request, file=pdf_file)

Result:
- PASS: Successfully processed via /v1/convert/file/async
- PASS: Polling completed (task_status: success)
- PASS: Result retrieved from /v1/result/{task_id}
- Processing time: 5089ms (includes polling overhead)
- Content returned: 1486 characters markdown

Test 2: Automatic fallback on async failure

# Simulate async endpoint unavailable (stop container)
docker stop docling-test

config = DoclingServeFileProcessorConfig(mode="async")
result = await processor.process_file(request, file=pdf_file)

Result:
- PASS: Async attempt failed (connection error)
- PASS: Warning logged: "Async API request failed, falling back to sync endpoints"
- PASS: Sync fallback attempted (also failed because container stopped)
- Proves fallback mechanism triggers correctly

Test 3: Sync mode works independently

config = DoclingServeFileProcessorConfig(mode="sync")
result = await processor.process_file(request, file=pdf_file)

Result:
- PASS: No async attempt (mode="sync")
- PASS: Sync endpoint used: /v1/convert/file
- Processing time: 2026ms (faster, no polling)
- Same content output as async mode

Test 4: Default mode is async

config = DoclingServeFileProcessorConfig()  # no mode specified
assert config.mode == "async"

Result: PASS - Defaults to async as expected

Test Setup

- Docling Serve: Local instance via Docker (quay.io/docling-project/docling-serve) - which should work the same as IBM SaaS endpoint.
- Test file: ogx_and_models.pdf (86 pages, 63MB, from integration test fixtures)
- Endpoints tested:
  - /v1/convert/file/async (async submit)
  - /v1/status/poll/{task_id} (polling)
  - /v1/result/{task_id} (result retrieval)
  - /v1/convert/file (sync fallback)
- Polling interval: 5 seconds (fixed, based on docling community examples)