OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
"""
Unit tests for services/docling_service.py
Validates async conversion logic, polling behavior, and error handling.
"""
from unittest.mock import AsyncMock, MagicMock, patch
import httpx
import pytest
from services.docling_service import (
PASSWORD_PROTECTED_PDF_DETAIL,
DoclingPayloadTooLarge,
DoclingServeError,
DoclingService,
is_encrypted_pdf,
password_protected_pdf_error,
)
from utils.upload_limits import UploadTooLarge
# Shape of a /v1/result body for a password-protected PDF: the task ran to
# completion, but the conversion failed and no document was exported.
_PASSWORD_PROTECTED_RESULT = {
"status": "failure",
"errors": [
{
"component_type": "user_input",
"module_name": "",
"error_message": (
"docling-parse could not load document abc123: "
"Failed to load document (PDFium: Incorrect password error)."
),
}
],
"document": {"filename": "secret.pdf", "json_content": None},
}
def _make_response(status_code: int, json_data: dict = None) -> MagicMock:
"""Create a mock HTTP response."""
resp = MagicMock(spec=httpx.Response)
resp.status_code = status_code
resp.json.return_value = json_data or {}
# Mock raise_for_status to raise if status_code >= 400
if status_code >= 400:
def raise_status():
raise httpx.HTTPStatusError("Error", request=MagicMock(), response=resp)
resp.raise_for_status.side_effect = raise_status
else:
resp.raise_for_status.return_value = None
return resp
@pytest.fixture
def mock_httpx_client():
"""Provide a mocked httpx AsyncClient."""
client = AsyncMock(spec=httpx.AsyncClient)
# Mock __aenter__ and __aexit__ for 'async with client' support
client.__aenter__.return_value = client
return client
@pytest.fixture
def docling_service(mock_httpx_client):
"""Provide a DoclingService instance with a mocked client."""
return DoclingService(docling_url="http://docling:8000", httpx_client=mock_httpx_client)
@pytest.fixture(autouse=True)
def no_sleep():
"""Patch asyncio.sleep so tests run instantly."""
with patch("services.docling_service.asyncio.sleep", new_callable=AsyncMock) as mock_sleep:
yield mock_sleep
# ── Polling Logic ───────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_poll_result_success(docling_service, mock_httpx_client):
"""Returns json_content when Docling returns 'success'."""
# First call: status poll -> success
# Second call: get result -> document data
mock_httpx_client.get.side_effect = [
_make_response(200, {"task_status": "success"}),
_make_response(200, {"document": {"json_content": {"key": "value"}}}),
]
result = await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
assert result == {"key": "value"}
assert mock_httpx_client.get.call_count == 2
# Verify URLs
calls = mock_httpx_client.get.call_args_list
assert calls[0].args[0].endswith("/v1/status/poll/task123")
assert calls[1].args[0].endswith("/v1/result/task123")
@pytest.mark.asyncio
async def test_poll_result_waits_for_pending(docling_service, mock_httpx_client, no_sleep):
"""Polls multiple times if status is 'pending' before succeeding."""
mock_httpx_client.get.side_effect = [
_make_response(200, {"task_status": "pending"}),
_make_response(200, {"task_status": "pending"}),
_make_response(200, {"task_status": "success"}),
_make_response(200, {"document": {"json_content": {"key": "value"}}}),
]
result = await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
assert result == {"key": "value"}
assert mock_httpx_client.get.call_count == 4
assert no_sleep.call_count == 2
@pytest.mark.asyncio
async def test_poll_result_failure_status(docling_service, mock_httpx_client):
"""Raises DoclingServeError when status is 'failure'."""
mock_httpx_client.get.return_value = _make_response(200, {"task_status": "failure"})
with pytest.raises(DoclingServeError, match="Docling processing failed"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
@pytest.mark.asyncio
async def test_poll_result_timeout(docling_service, mock_httpx_client, no_sleep):
"""Raises TimeoutError when task stays pending beyond timeout."""
mock_httpx_client.get.return_value = _make_response(200, {"task_status": "pending"})
# timeout=2.0, interval=1.0 -> loop runs at T=0, T=1, exits at T=2
with pytest.raises(TimeoutError, match="did not complete within"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 2.0)
assert mock_httpx_client.get.call_count == 2
assert no_sleep.call_count == 2
@pytest.mark.asyncio
async def test_poll_result_missing_content(docling_service, mock_httpx_client):
"""Raises DoclingServeError if result response is missing json_content."""
mock_httpx_client.get.side_effect = [
_make_response(200, {"task_status": "success"}),
_make_response(200, {"document": {}}), # No json_content
]
with pytest.raises(DoclingServeError, match="missing document.json_content"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
@pytest.mark.asyncio
async def test_poll_result_surfaces_conversion_failure_from_result_payload(
docling_service, mock_httpx_client
):
"""A 'success' task whose *conversion* failed reports the real cause.
docling-serve marks the task successful once the job ran; a password-protected
PDF then yields a result body with status="failure", an errors list and a null
json_content. The errors must win over the generic "missing json_content".
"""
mock_httpx_client.get.side_effect = [
_make_response(200, {"task_status": "success"}),
_make_response(200, _PASSWORD_PROTECTED_RESULT),
]
with pytest.raises(DoclingServeError) as exc_info:
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
message = str(exc_info.value)
assert message.startswith("Docling processing failed: ")
assert "Incorrect password" in message
assert "missing document.json_content" not in message
# ── Password-protected PDFs on newer docling ───────────────────────
# docling >= 2.141 loads through docling-parse first, whose load failure no longer
# names the reason (seen on CPD, tracker #99817).
_DOCLING_PARSE_LOAD_FAILURE = (
"Docling processing failed: docling-parse could not load document 8fc525: "
"Failed to load document with key key=8fc525"
)
_XREF_TABLE = b"xref\n0 1\n0000000000 65535 f \n"
def _pdf(body: bytes, trailer: bytes, *, junk: bytes = b"") -> bytes:
"""Minimal classic-xref PDF; with ``junk``, offsets are relative to the header."""
head = b"%PDF-1.7\n" + body
return junk + head + _XREF_TABLE + trailer + b"\nstartxref\n%d\n%%%%EOF\n" % len(head)
def _append_revision(pdf: bytes, body: bytes, trailer: bytes) -> bytes:
"""Append an incremental update whose trailer becomes the active one."""
head = pdf + body
return head + _XREF_TABLE + trailer + b"\nstartxref\n%d\n%%%%EOF\n" % len(head)
def _xref_stream_pdf(entries: bytes, data: bytes) -> bytes:
"""Minimal PDF whose active cross-reference section is an xref stream."""
head = b"%PDF-1.5\n"
xref = b"9 0 obj\n<< /Type /XRef %s /Length %d >>\nstream\n%s\nendstream\nendobj\n" % (
entries,
len(data),
data,
)
return head + xref + b"startxref\n%d\n%%%%EOF\n" % len(head)
def _stale_startxref_pdf(objects: bytes) -> bytes:
"""PDF whose ``startxref`` names the first of ``objects`` rather than an xref section."""
head = b"%PDF-1.5\n"
return head + objects + b"startxref\n%d\n%%%%EOF\n" % len(head)
_CATALOG = b"1 0 obj\n<< /Type /Catalog >>\nendobj\n"
_ENCRYPTED_PDF = _pdf(_CATALOG, b"trailer\n<< /Root 1 0 R /Encrypt 5 0 R /Size 6 >>")
_PLAIN_PDF = _pdf(_CATALOG, b"trailer\n<< /Root 1 0 R >>")
# Unencrypted, but a content stream shows the literal text "/Encrypt 1 0 R".
_PLAIN_PDF_WITH_ENCRYPT_TEXT = _pdf(
_CATALOG + b"4 0 obj\n<< /Length 25 >>\nstream\nBT (/Encrypt 1 0 R) Tj ET\nendstream\nendobj\n",
b"trailer\n<< /Root 1 0 R >>",
)
@pytest.mark.parametrize(
("content", "expected"),
[
pytest.param(_ENCRYPTED_PDF, True, id="classic-trailer-encrypted"),
pytest.param(
_xref_stream_pdf(b"/Encrypt << /Filter /Standard >>", b"abc"),
True,
id="xref-stream-encrypted",
),
pytest.param(
_append_revision(
_ENCRYPTED_PDF,
b"2 0 obj\n<< /Type /Page >>\nendobj\n",
b"trailer\n<< /Root 1 0 R /Prev %d /Encrypt 5 0 R /Size 6 >>"
% _ENCRYPTED_PDF.index(b"xref"),
),
True,
id="incremental-update-encrypted",
),
pytest.param(
_pdf(_CATALOG, b"trailer\n<< /Root 1 0 R /Encrypt 5 0 R >>", junk=b"JUNK\n"),
True,
id="junk-before-header",
),
pytest.param(_PLAIN_PDF, False, id="classic-trailer-plain"),
pytest.param(_PLAIN_PDF_WITH_ENCRYPT_TEXT, False, id="encrypt-in-content-stream"),
pytest.param(
_xref_stream_pdf(b"", b"/Encrypt 1 0 R"), False, id="encrypt-in-xref-stream-data"
),
pytest.param(
b"%PDF-1.7\n" + _CATALOG + b"trailer\n<< /Root 1 0 R /Encrypt 5 0 R >>\n",
False,
id="truncated-no-startxref",
),
pytest.param(
b"%PDF-1.7\ntrailer\n<< /Encrypt 5 0 R >>\nstartxref\n3\n%%EOF\n",
False,
id="startxref-points-at-garbage",
),
pytest.param(
_stale_startxref_pdf(b"3 0 obj\n<< /Type /Filespec /Encrypt 5 0 R >>\nendobj\n"),
False,
id="startxref-points-at-non-xref-object",
),
pytest.param(
# The non-xref dictionary ends at `endobj`; the later xref stream's
# /Type /XRef and /Encrypt must not be read as belonging to it.
_stale_startxref_pdf(
b"3 0 obj\n<< /Type /Filespec >>\nendobj\n"
b"9 0 obj\n<< /Type /XRef /Encrypt 5 0 R /Length 3 >>\nstream\nabc\n"
b"endstream\nendobj\n"
),
False,
id="startxref-points-at-object-before-xref-stream",
),
pytest.param(
# Offsets are relative to the header, as in the classic junk case.
b"JUNK\n" + _xref_stream_pdf(b"/Encrypt 5 0 R", b"abc"),
True,
id="xref-stream-junk-before-header",
),
pytest.param(b"not a pdf /Encrypt 5 0 R startxref 0", False, id="not-a-pdf"),
],
)
def test_is_encrypted_pdf(content, expected):
assert is_encrypted_pdf(content) is expected
def test_password_protected_pdf_error_needs_load_failure_and_encryption():
assert (
password_protected_pdf_error(_DOCLING_PARSE_LOAD_FAILURE, _ENCRYPTED_PDF)
== PASSWORD_PROTECTED_PDF_DETAIL
)
# A corrupt but unencrypted PDF keeps docling's own message.
assert password_protected_pdf_error(_DOCLING_PARSE_LOAD_FAILURE, _PLAIN_PDF) is None
# An owner-password-only PDF that failed for another reason is not relabelled.
assert (
password_protected_pdf_error("Docling processing failed: OCR crashed", _ENCRYPTED_PDF)
is None
)
@pytest.mark.asyncio
async def test_convert_bytes_names_password_protected_pdf(docling_service):
with (
patch.object(
docling_service, "upload_to_docling_direct_async", AsyncMock(return_value="t1")
),
patch.object(
docling_service,
"get_docling_result_async",
AsyncMock(side_effect=DoclingServeError(_DOCLING_PARSE_LOAD_FAILURE)),
),
pytest.raises(DoclingServeError) as exc_info,
):
await docling_service.convert_bytes(_ENCRYPTED_PDF, "secret.pdf")
assert str(exc_info.value) == f"Docling processing failed: {PASSWORD_PROTECTED_PDF_DETAIL}"
assert str(exc_info.value.__cause__) == _DOCLING_PARSE_LOAD_FAILURE
@pytest.mark.asyncio
async def test_convert_bytes_keeps_docling_error_when_encrypt_appears_outside_trailer(
docling_service,
):
"""Literal /Encrypt text in page content must not relabel an unrelated load failure."""
with (
patch.object(
docling_service, "upload_to_docling_direct_async", AsyncMock(return_value="t1")
),
patch.object(
docling_service,
"get_docling_result_async",
AsyncMock(side_effect=DoclingServeError(_DOCLING_PARSE_LOAD_FAILURE)),
),
pytest.raises(DoclingServeError) as exc_info,
):
await docling_service.convert_bytes(_PLAIN_PDF_WITH_ENCRYPT_TEXT, "about-pdf.pdf")
assert str(exc_info.value) == _DOCLING_PARSE_LOAD_FAILURE
@pytest.mark.asyncio
async def test_convert_file_keeps_docling_error_for_unencrypted_pdf(docling_service, tmp_path):
pdf = tmp_path / "broken.pdf"
pdf.write_bytes(_PLAIN_PDF)
with (
patch.object(
docling_service, "upload_to_docling_direct_async", AsyncMock(return_value="t1")
),
patch.object(
docling_service,
"get_docling_result_async",
AsyncMock(side_effect=DoclingServeError(_DOCLING_PARSE_LOAD_FAILURE)),
),
pytest.raises(DoclingServeError, match="Failed to load document with key"),
):
await docling_service.convert_file(str(pdf))
@pytest.mark.asyncio
async def test_poll_result_http_error(docling_service, mock_httpx_client):
"""Propagates HTTP errors during polling as DoclingServeError."""
mock_httpx_client.get.return_value = _make_response(500)
with pytest.raises(DoclingServeError, match="Error polling docling status"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
# ── Upload Logic ────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_upload_success(docling_service, mock_httpx_client):
"""Returns task_id on successful upload."""
mock_httpx_client.post.return_value = _make_response(200, {"task_id": "new-task-id"})
# Mock config to avoid missing attribute errors during _build_docling_options
with patch("services.docling_service.get_openrag_config") as mock_get_config:
mock_config = MagicMock()
mock_config.knowledge.table_structure = False
mock_config.knowledge.ocr = False
mock_config.knowledge.picture_descriptions = False
mock_config.knowledge.vlm_enabled = False
mock_get_config.return_value = mock_config
task_id = await docling_service.upload_to_docling_direct_async("test.pdf", b"data")
assert task_id == "new-task-id"
assert mock_httpx_client.post.call_count == 1
# Verify boolean serialization (bool -> "true"/"false")
_, kwargs = mock_httpx_client.post.call_args
data = kwargs.get("data", {})
assert data["do_ocr"] == "false"
@pytest.mark.asyncio
async def test_upload_http_error(docling_service, mock_httpx_client):
"""Raises exception if upload returns non-200."""
mock_httpx_client.post.return_value = _make_response(400)
with patch("services.docling_service.get_openrag_config") as mock_get_config:
mock_config = MagicMock()
mock_config.knowledge.table_structure = False
mock_config.knowledge.ocr = False
mock_config.knowledge.picture_descriptions = False
mock_config.knowledge.vlm_enabled = False
mock_get_config.return_value = mock_config
with pytest.raises(httpx.HTTPStatusError):
await docling_service.upload_to_docling_direct_async("test.pdf", b"data")
@pytest.mark.asyncio
async def test_upload_refuses_before_posting_when_over_the_limit(
docling_service, mock_httpx_client, monkeypatch
):
monkeypatch.setattr("config.settings.OPENRAG_MAX_UPLOAD_MB", 1)
with pytest.raises(UploadTooLarge, match="big.pdf"):
await docling_service.upload_to_docling_direct_async("big.pdf", b"x" * (1024 * 1024 + 1))
mock_httpx_client.post.assert_not_called()
@pytest.mark.asyncio
async def test_upload_maps_docling_proxy_413(docling_service, mock_httpx_client):
"""A 413 from the proxy becomes a message that names the file and the fix."""
mock_httpx_client.post.return_value = _make_response(413)
with patch("services.docling_service.get_openrag_config") as mock_get_config:
mock_config = MagicMock()
mock_config.knowledge.table_structure = False
mock_config.knowledge.ocr = False
mock_config.knowledge.picture_descriptions = False
mock_config.knowledge.vlm_enabled = False
mock_get_config.return_value = mock_config
with (
patch("services.docling_service.logger") as mock_logger,
pytest.raises(DoclingPayloadTooLarge, match="report.pdf") as exc_info,
):
await docling_service.upload_to_docling_direct_async("report.pdf", b"data")
message = str(exc_info.value)
assert "document-processing service" in message
assert "within the configured upload limit" in message
assert "OPENRAG_MAX_UPLOAD_MB" in message
assert "http://docling:8000" not in message
assert "client_max_body_size" not in message
logged = mock_logger.error.call_args.kwargs["error"]
assert "http://docling:8000/v1/convert/file/async" in logged
assert "client_max_body_size" in logged
# ── Configuration Logic ─────────────────────────────────────────────
@pytest.mark.asyncio
async def test_build_docling_options_toggles(docling_service):
"""Correctly maps OpenRAG config to Docling options."""
mock_config = MagicMock()
mock_config.knowledge.table_structure = True
mock_config.knowledge.ocr = True
mock_config.knowledge.picture_descriptions = False
mock_config.knowledge.vlm_enabled = False
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
options = await docling_service._build_docling_options_async()
assert options["do_table_structure"] is True
assert options["do_ocr"] is True
assert options["do_picture_description"] is False
assert options["to_formats"] == "json"
assert options["image_export_mode"] == "placeholder"
assert "include_page_images" not in options
assert "include_images" not in options
@pytest.mark.asyncio
async def test_build_docling_options_preview_mode_embeds_page_images(docling_service):
"""Preview mode requests embedded page rasters for PDF bbox overlays."""
mock_config = MagicMock()
mock_config.knowledge.table_structure = False
mock_config.knowledge.ocr = False
mock_config.knowledge.picture_descriptions = False
mock_config.knowledge.vlm_enabled = False
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
options = await docling_service._build_docling_options_async(preview_mode=True)
assert options["to_formats"] == "json"
assert options["image_export_mode"] == "embedded"
assert options["include_page_images"] is True
assert options["include_images"] is True
@pytest.mark.asyncio
async def test_build_docling_options_sends_configured_ocr_languages(docling_service):
"""OCR languages from KnowledgeConfig reach docling as engine-specific codes."""
mock_config = MagicMock()
mock_config.knowledge.table_structure = False
mock_config.knowledge.ocr = True
mock_config.knowledge.ocr_languages = ["en", "ja"]
mock_config.knowledge.picture_descriptions = False
mock_config.knowledge.vlm_enabled = False
with (
patch("services.docling_service.get_openrag_config", return_value=mock_config),
patch("services.docling_service.platform.system", return_value="Darwin"),
):
options = await docling_service._build_docling_options_async()
assert options["ocr_lang"] == ["ja-JP", "en-US"]
@pytest.mark.asyncio
async def test_upload_sends_ocr_lang_as_repeated_form_fields(docling_service, mock_httpx_client):
"""httpx encodes a list form value as repeated parts; docling needs that shape."""
mock_config = MagicMock()
mock_config.knowledge.table_structure = False
mock_config.knowledge.ocr = True
mock_config.knowledge.ocr_languages = ["en", "ja"]
mock_config.knowledge.picture_descriptions = False
mock_config.knowledge.vlm_enabled = False
mock_httpx_client.post.return_value = _make_response(200, {"task_id": "t1"})
with (
patch("services.docling_service.get_openrag_config", return_value=mock_config),
patch("services.docling_service.platform.system", return_value="Darwin"),
):
await docling_service.upload_to_docling_direct_async("doc.pdf", b"data")
sent = mock_httpx_client.post.call_args.kwargs["data"]
assert sent["ocr_lang"] == ["ja-JP", "en-US"]
assert sent["ocr_preset"] == "ocrmac"
assert "ocr_engine" not in sent
def test_preset_configs_macos():
"""Uses ocrmac engine on macOS."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Darwin"):
preset = get_docling_preset_configs(ocr=True)
assert preset["ocr_preset"] == "ocrmac"
def test_preset_configs_linux():
"""Uses easyocr engine on non-macOS."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Linux"):
preset = get_docling_preset_configs(ocr=True)
assert preset["ocr_preset"] == "easyocr"
def test_preset_configs_never_sends_deprecated_ocr_engine():
"""Use the supported preset field rather than the deprecated engine field."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Darwin"):
preset = get_docling_preset_configs(ocr=True, ocr_languages=["ja", "en"])
assert "ocr_engine" not in preset
def test_preset_configs_maps_languages_to_ocrmac_codes():
"""ocrmac wants BCP-47 tags, not the neutral codes stored in config."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Darwin"):
preset = get_docling_preset_configs(ocr=True, ocr_languages=["ja", "en", "vi"])
assert preset["ocr_lang"] == ["ja-JP", "vi-VN", "en-US"]
def test_preset_configs_maps_languages_to_easyocr_codes():
"""easyocr wants short codes, and its own spelling for Chinese."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Linux"):
preset = get_docling_preset_configs(ocr=True, ocr_languages=["ja", "zh-Hans"])
assert preset["ocr_lang"] == ["ja", "ch_sim"]
def test_preset_configs_passes_through_unknown_language_codes():
"""An engine code the map does not know is forwarded rather than dropped."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Linux"):
preset = get_docling_preset_configs(ocr=True, ocr_languages=["bn"])
assert preset["ocr_lang"] == ["bn"]
def test_preset_configs_omits_ocr_lang_when_no_languages_configured():
"""Empty config must not send an empty list that would override engine defaults."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Darwin"):
preset = get_docling_preset_configs(ocr=True, ocr_languages=[])
assert "ocr_lang" not in preset
def test_init_default_url():
"""Uses DOCLING_SERVE_URL from config.settings if not provided."""
with patch("services.docling_service.DOCLING_SERVE_URL", "http://default:5001"):
service = DoclingService()
assert service.docling_url == "http://default:5001"
# ── VLM Pipeline Options ────────────────────────────────────────────
def _vlm_mock_config(provider: str) -> MagicMock:
mock_config = MagicMock()
k = mock_config.knowledge
k.vlm_enabled = True
k.vlm_provider = provider
k.vlm_model = "gpt-4o" if provider == "openai" else "meta-llama/llama-vision"
k.vlm_prompt = "Extract all text."
k.vlm_response_format = "markdown"
k.vlm_max_tokens = 5000
k.vlm_concurrency = 4
k.vlm_timeout = 120
k.vlm_openai_url = "https://api.openai.com/v1/chat/completions"
k.vlm_watsonx_api_version = "2023-05-29"
k.table_structure = False
k.ocr = False
k.picture_descriptions = True
mock_config.providers.openai.api_key = "sk-test"
mock_config.providers.watsonx.api_key = "wx-key"
mock_config.providers.watsonx.endpoint = "https://us-south.ml.cloud.ibm.com/"
mock_config.providers.watsonx.project_id = "proj-123"
return mock_config
@pytest.mark.asyncio
async def test_build_vlm_options_openai(docling_service):
"""OpenAI VLM options carry the provider key and chat-completions params."""
mock_config = _vlm_mock_config("openai")
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
options = await docling_service._build_docling_options_async()
assert options["do_picture_description"] is True
assert options["to_formats"] == "json"
api = options["picture_description_api"]
assert api["url"] == "https://api.openai.com/v1/chat/completions"
assert api["headers"]["Authorization"] == "Bearer sk-test"
assert api["params"] == {"model": "gpt-4o", "max_completion_tokens": 5000}
assert api["prompt"] == "Extract all text."
@pytest.mark.asyncio
async def test_build_vlm_options_watsonx(docling_service):
"""watsonx VLM options exchange the API key for an IAM bearer token."""
mock_config = _vlm_mock_config("watsonx")
with (
patch("services.docling_service.get_openrag_config", return_value=mock_config),
patch(
"enhancements.providers.watsonx.iam.get_iam_token", new_callable=AsyncMock
) as mock_token,
):
mock_token.return_value = "iam-token"
options = await docling_service._build_docling_options_async()
mock_token.assert_awaited_once_with("wx-key")
api = options["picture_description_api"]
assert api["url"] == "https://us-south.ml.cloud.ibm.com/ml/v1/text/chat?version=2023-05-29"
assert api["headers"]["Authorization"] == "Bearer iam-token"
assert api["params"] == {
"model_id": "meta-llama/llama-vision",
"project_id": "proj-123",
"max_tokens": 5000,
}
@pytest.mark.asyncio
async def test_build_vlm_options_watsonx_unconfigured(docling_service):
"""Raises DoclingServeError when watsonx provider is incomplete."""
mock_config = _vlm_mock_config("watsonx")
mock_config.providers.watsonx.project_id = ""
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
with pytest.raises(DoclingServeError, match="watsonx provider is not fully"):
await docling_service._build_docling_options_async()
@pytest.mark.asyncio
async def test_build_vlm_options_ollama(docling_service):
"""Ollama VLM options carry the provider endpoint and chat-completions params."""
mock_config = _vlm_mock_config("ollama")
mock_config.providers.ollama.endpoint = "http://localhost:11434"
mock_config.providers.ollama.configured = True
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
options = await docling_service._build_docling_options_async()
assert options["do_picture_description"] is True
assert options["to_formats"] == "json"
api = options["picture_description_api"]
assert api["url"] == "http://localhost:11434/v1/chat/completions"
assert api["headers"] == {}
assert api["params"] == {"model": "meta-llama/llama-vision", "max_completion_tokens": 5000}
assert api["prompt"] == "Extract all text."
@pytest.mark.asyncio
async def test_build_vlm_options_azure(docling_service):
"""Azure VLM options carry the deployment URL, api-key header, and completion params."""
mock_config = _vlm_mock_config("azure")
mock_config.knowledge.vlm_model = "azure/gpt-4.1"
mock_config.providers.credential_values = lambda provider: {
"api_key": "azure-key",
"api_base": "https://example.openai.azure.com",
"api_version": "2024-02-01",
}
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
options = await docling_service._build_docling_options_async()
assert options["do_picture_description"] is True
api = options["picture_description_api"]
assert (
api["url"]
== "https://example.openai.azure.com/openai/deployments/gpt-4.1/chat/completions?api-version=2024-02-01"
)
assert api["headers"] == {"api-key": "azure-key"}
assert api["params"] == {"model": "gpt-4.1", "max_completion_tokens": 5000}
assert api["prompt"] == "Extract all text."
@pytest.mark.asyncio
async def test_build_vlm_options_azure_rejects_non_https(docling_service):
"""Azure VLM options reject plain HTTP endpoints."""
mock_config = _vlm_mock_config("azure")
mock_config.knowledge.vlm_model = "azure/gpt-4.1"
mock_config.providers.credential_values = lambda provider: {
"api_key": "azure-key",
"api_base": "http://example.openai.azure.com",
}
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
with pytest.raises(DoclingServeError, match="Azure VLM endpoint must use HTTPS"):
await docling_service._build_docling_options_async()
@pytest.mark.asyncio
async def test_upload_vlm_enabled_sends_vlm_form_fields(docling_service, mock_httpx_client):
"""VLM upload sends custom picture description parameters."""
import json as json_lib
mock_httpx_client.post.return_value = _make_response(200, {"task_id": "vlm-task"})
mock_config = _vlm_mock_config("openai")
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
task_id = await docling_service.upload_to_docling_direct_async("test.pdf", b"data")
assert task_id == "vlm-task"
_, kwargs = mock_httpx_client.post.call_args
data = kwargs.get("data", {})
assert data["do_picture_description"] == "true"
api = json_lib.loads(data["picture_description_api"])
assert api["params"]["model"] == "gpt-4o"
@pytest.mark.asyncio
async def test_build_vlm_options_azure_ai_foundry(docling_service):
"""Foundry keeps its own endpoint shape instead of falling back to OpenAI.
`azure_ai` is Azure AI Foundry, not the Azure OpenAI Service: its api_base
already points at the `/models` route, so chat completions hang directly
off it rather than under `/openai/deployments/<name>`.
"""
mock_config = _vlm_mock_config("azure_ai")
mock_config.knowledge.vlm_model = "azure_ai/mistral-small-2503"
mock_config.providers.credential_values = lambda provider: {
"api_key": "foundry-key",
"api_base": "https://example.services.ai.azure.com/models",
"api_version": "2024-05-01-preview",
}
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
options = await docling_service._build_docling_options_async()
api = options["picture_description_api"]
assert api["url"] == (
"https://example.services.ai.azure.com/models/chat/completions"
"?api-version=2024-05-01-preview"
)
assert api["headers"] == {"api-key": "foundry-key"}
assert api["params"] == {"model": "mistral-small-2503", "max_completion_tokens": 5000}
@pytest.mark.asyncio
async def test_build_vlm_options_azure_ai_requires_credentials(docling_service):
mock_config = _vlm_mock_config("azure_ai")
mock_config.providers.credential_values = lambda provider: {}
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
with pytest.raises(DoclingServeError, match="Azure AI Foundry provider is not"):
await docling_service._build_docling_options_async()
def test_docling_config_model_accepts_preset_output():
"""DoclingConfig validates the dict get_docling_preset_configs produces."""
from services.docling_service import DoclingConfig, get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Darwin"):
preset = get_docling_preset_configs(ocr=True, ocr_languages=["en", "ja"])
config = DoclingConfig(**preset)
assert config.ocr_preset == "ocrmac"
assert config.ocr_lang == ["ja-JP", "en-US"]
def test_preset_configs_maps_arabic_per_engine():
"""Arabic is in the curated set; ocrmac and easyocr spell it differently."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Darwin"):
mac = get_docling_preset_configs(ocr=True, ocr_languages=["ar"])
with patch("services.docling_service.platform.system", return_value="Linux"):
linux = get_docling_preset_configs(ocr=True, ocr_languages=["ar"])
assert mac["ocr_lang"] == ["ar-SA"]
assert linux["ocr_lang"] == ["ar"]