Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
14.2 KB
Raw Blame
"""Unit tests for the two-phase Docling + Langflow ingestion flow.

Verifies the core architectural property: when a polling service is provided,
``LangflowFileService.upload_and_ingest_file`` must NOT invoke the Langflow
ingestion flow until Docling reports SUCCESS, and must NEVER invoke it when
Docling fails / expires / times out.
"""

from types import SimpleNamespace
from unittest.mock import AsyncMock

import pytest

from models.tasks import (
    DoclingPhaseStatus,
    FileTask,
    IngestionPhase,
)
from services.docling_polling_service import DoclingPollResult, PollOutcome
from services.langflow_file_service import LangflowFileService


@pytest.fixture
def file_tuple():
    return ("test.pdf", b"PDFDATA", "application/pdf")


@pytest.fixture
def file_task():
    return FileTask(file_path="/tmp/test.pdf", filename="test.pdf")


@pytest.fixture
def mock_docling_service():
    svc = AsyncMock()
    svc.upload_to_docling_direct_async.return_value = "task-abc-123"
    return svc


@pytest.fixture
def mock_polling_service():
    return AsyncMock()


@pytest.fixture
def langflow_service(mock_docling_service):
    svc = LangflowFileService(docling_service=mock_docling_service)
    # Stub the actual Langflow HTTP call — those have their own coverage.
    svc.run_ingestion_flow = AsyncMock(return_value={"status": "ok"})
    return svc


@pytest.mark.asyncio
async def test_two_phase_success_invokes_langflow_with_task_id(
    langflow_service, mock_docling_service, mock_polling_service, file_tuple, file_task
):
    mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
        outcome=PollOutcome.SUCCESS, elapsed_seconds=2.5
    )

    result = await langflow_service.upload_and_ingest_file(
        file_tuple=file_tuple,
        docling_polling_service=mock_polling_service,
        file_task=file_task,
        owner="owner-123",
        jwt_token="Bearer jwt-token",
    )

    mock_docling_service.upload_to_docling_direct_async.assert_awaited_once_with(
        "test.pdf",
        b"PDFDATA",
        user_id="owner-123",
        auth_header="Bearer jwt-token",
        ocr=None,
        picture_descriptions=None,
        preview_mode=False,
    )

    # Langflow was invoked exactly once, with the docling_task_id forwarded.
    assert langflow_service.run_ingestion_flow.call_count == 1
    kwargs = langflow_service.run_ingestion_flow.call_args.kwargs
    assert kwargs["docling_task_id"] == "task-abc-123"

    # FileTask reflects full lifecycle.
    assert file_task.docling_task_id == "task-abc-123"
    assert file_task.docling_status == DoclingPhaseStatus.SUCCESS
    assert file_task.phase == IngestionPhase.COMPLETE

    # Result envelope.
    assert result["status"] == "success"
    assert result["docling_task_id"] == "task-abc-123"


@pytest.mark.asyncio
async def test_langflow_not_invoked_on_docling_failure(
    langflow_service, mock_polling_service, file_tuple, file_task
):
    mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
        outcome=PollOutcome.FAILED, detail="OCR engine crashed"
    )

    with pytest.raises(Exception, match="OCR engine crashed"):
        await langflow_service.upload_and_ingest_file(
            file_tuple=file_tuple,
            docling_polling_service=mock_polling_service,
            file_task=file_task,
        )

    # Crucial assertion — Langflow must never run when Docling failed.
    assert langflow_service.run_ingestion_flow.call_count == 0
    assert file_task.docling_status == DoclingPhaseStatus.FAILED
    # Phase remains DOCLING (never advanced to LANGFLOW).
    assert file_task.phase == IngestionPhase.DOCLING


@pytest.mark.asyncio
async def test_docling_load_failure_on_encrypted_pdf_names_password_protection(
    langflow_service, mock_polling_service, file_task
):
    """Newer docling drops the PDFium reason; the bytes still show the PDF is encrypted."""
    head = b"%PDF-1.7\n1 0 obj\n<< /Type /Catalog >>\nendobj\n"
    pdf = (
        head
        + b"xref\n0 1\n0000000000 65535 f \ntrailer\n<< /Root 1 0 R /Encrypt 5 0 R >>\n"
        + b"startxref\n%d\n%%%%EOF\n" % len(head)
    )
    encrypted = ("secret.pdf", pdf, "application/pdf")
    mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
        outcome=PollOutcome.FAILED,
        detail=(
            "Docling result unavailable after SUCCESS status: Docling processing failed: "
            "docling-parse could not load document 8fc525: "
            "Failed to load document with key key=8fc525"
        ),
    )

    with pytest.raises(Exception) as exc_info:
        await langflow_service.upload_and_ingest_file(
            file_tuple=encrypted,
            docling_polling_service=mock_polling_service,
            file_task=file_task,
        )

    message = str(exc_info.value)
    assert message.startswith("Docling conversion did not complete (failed): ")
    assert "Incorrect password" in message
    assert "with key" not in message
    assert langflow_service.run_ingestion_flow.call_count == 0


@pytest.mark.asyncio
async def test_docling_load_failure_on_unencrypted_pdf_keeps_docling_detail(
    langflow_service, mock_polling_service, file_tuple, file_task
):
    detail = "docling-parse could not load document 8fc525: Failed to load document with key k"
    mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
        outcome=PollOutcome.FAILED, detail=detail
    )

    with pytest.raises(Exception, match="Failed to load document with key k"):
        await langflow_service.upload_and_ingest_file(
            file_tuple=file_tuple,
            docling_polling_service=mock_polling_service,
            file_task=file_task,
        )


@pytest.mark.asyncio
async def test_langflow_not_invoked_on_docling_expired(
    langflow_service, mock_polling_service, file_tuple, file_task
):
    mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
        outcome=PollOutcome.EXPIRED, detail="task not found"
    )

    with pytest.raises(Exception, match="expired"):
        await langflow_service.upload_and_ingest_file(
            file_tuple=file_tuple,
            docling_polling_service=mock_polling_service,
            file_task=file_task,
        )

    assert langflow_service.run_ingestion_flow.call_count == 0
    assert file_task.docling_status == DoclingPhaseStatus.EXPIRED


@pytest.mark.asyncio
async def test_langflow_not_invoked_on_polling_timeout(
    langflow_service, mock_polling_service, file_tuple, file_task
):
    mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
        outcome=PollOutcome.TIMEOUT, detail="exceeded 1800s"
    )

    with pytest.raises(Exception, match="timeout"):
        await langflow_service.upload_and_ingest_file(
            file_tuple=file_tuple,
            docling_polling_service=mock_polling_service,
            file_task=file_task,
        )

    assert langflow_service.run_ingestion_flow.call_count == 0
    assert file_task.docling_status == DoclingPhaseStatus.FAILED


@pytest.mark.asyncio
async def test_phase_progresses_only_after_polling_succeeds(
    langflow_service, mock_polling_service, file_tuple, file_task
):
    """Phase must be DOCLING during polling, then LANGFLOW, then COMPLETE."""
    observed_phases = []

    async def record_then_succeed(*args, **kwargs):
        observed_phases.append(file_task.phase)
        return DoclingPollResult(outcome=PollOutcome.SUCCESS)

    mock_polling_service.poll_until_ready.side_effect = record_then_succeed

    async def record_then_run(*args, **kwargs):
        observed_phases.append(file_task.phase)
        return {"status": "ok"}

    langflow_service.run_ingestion_flow = AsyncMock(side_effect=record_then_run)

    await langflow_service.upload_and_ingest_file(
        file_tuple=file_tuple,
        docling_polling_service=mock_polling_service,
        file_task=file_task,
    )

    assert observed_phases == [IngestionPhase.DOCLING, IngestionPhase.LANGFLOW]
    assert file_task.phase == IngestionPhase.COMPLETE


@pytest.mark.asyncio
async def test_legacy_path_without_polling_service_calls_langflow_directly(
    langflow_service, file_tuple, file_task
):
    """Backward compatibility: when no polling service is provided, Langflow
    is invoked immediately after Docling submission (Langflow handles polling).
    On success the file_task must end with docling_status=SUCCESS so the
    status fields stay coherent — Langflow returning success implies its
    DoclingRemote component consumed the task.
    """
    result = await langflow_service.upload_and_ingest_file(
        file_tuple=file_tuple,
        docling_polling_service=None,
        file_task=file_task,
    )

    assert langflow_service.run_ingestion_flow.call_count == 1
    kwargs = langflow_service.run_ingestion_flow.call_args.kwargs
    assert kwargs["docling_task_id"] == "task-abc-123"
    assert result["status"] == "success"
    # Status fields must not leave the task stuck in PROCESSING.
    assert file_task.docling_status == DoclingPhaseStatus.SUCCESS
    assert file_task.phase == IngestionPhase.COMPLETE
    assert file_task.docling_task_id == "task-abc-123"


def test_processor_default_polling_service_is_none():
    """LangflowFileProcessor no longer constructs a polling service inline.
    The container injects it; absent injection, the processor falls back
    to the legacy single-call path.
    """
    from models.processors import LangflowFileProcessor

    lf_svc = LangflowFileService(docling_service=AsyncMock())
    processor = LangflowFileProcessor(
        langflow_file_service=lf_svc, session_manager=None, allow_anonymous_delete=True
    )
    assert processor.docling_polling_service is None


def test_processor_accepts_injected_polling_service():
    """The polling service is passed through unchanged when injected."""
    from models.processors import LangflowFileProcessor

    lf_svc = LangflowFileService(docling_service=AsyncMock())
    injected = AsyncMock()
    processor = LangflowFileProcessor(
        langflow_file_service=lf_svc,
        session_manager=None,
        docling_polling_service=injected,
        allow_anonymous_delete=True,
    )
    assert processor.docling_polling_service is injected


@pytest.mark.asyncio
async def test_langflow_preflight_detects_embedding_dimensions_with_probe(monkeypatch):
    calls: list[tuple[str, list]] = []

    async def fake_embeddings(body, **_kwargs):
        calls.append((body["model"], body["input"]))
        return {"data": [{"embedding": [0.1] * 7}]}

    monkeypatch.setattr("services.llm_gateway.embeddings", fake_embeddings)

    svc = LangflowFileService(docling_service=AsyncMock())

    assert await svc._detect_embedding_dimensions("provider/model", "provider") == 7
    assert await svc._detect_embedding_dimensions("provider/model", "provider") == 7
    # One call for two invocations: the probe is cached per provider+model.
    # The id is provider-tagged with `:` so the gateway routes it to the
    # provider the caller named rather than to the configured default.
    #
    # `provider/model` is the legacy tagged spelling of the same id, so the
    # tag is replaced rather than stacked. Asserting `provider:provider/model`
    # here, as this did, encoded the double-tagging bug: the gateway strips
    # the colon tag and would ask LiteLLM for `provider/provider/model`.
    assert calls == [("provider:model", ["dimension probe"])]


@pytest.mark.asyncio
async def test_langflow_preflight_defaults_unset_embedding_provider_to_openai(monkeypatch):
    class FakeIndices:
        async def exists(self, *, index):
            return True

    fake_opensearch = SimpleNamespace(indices=FakeIndices())
    monkeypatch.setattr("services.langflow_file_service.clients.opensearch", fake_opensearch)
    monkeypatch.setattr(
        "config.settings.get_openrag_config",
        lambda: SimpleNamespace(knowledge=SimpleNamespace(embedding_provider=None)),
    )
    monkeypatch.setattr("config.settings.get_index_name", lambda: "documents")

    ensure_field = AsyncMock()
    monkeypatch.setattr("utils.embedding_fields.ensure_embedding_field_exists", ensure_field)

    svc = LangflowFileService(docling_service=AsyncMock())
    svc._detect_embedding_dimensions = AsyncMock(return_value=1536)

    await svc._ensure_langflow_ingest_index("text-embedding-3-small")

    svc._detect_embedding_dimensions.assert_awaited_once_with("text-embedding-3-small", "openai")
    ensure_field.assert_awaited_once_with(
        fake_opensearch,
        "openai:text-embedding-3-small",
        "documents",
        1536,
    )


@pytest.mark.asyncio
async def test_task_service_threads_polling_service_to_processor(monkeypatch):
    """TaskService.create_langflow_upload_task must forward its injected
    polling service to the LangflowFileProcessor it constructs. This is the
    DI contract that replaces the processor's inline construction.
    """
    from services.task_service import TaskService

    injected = AsyncMock()
    captured: dict = {}

    class FakeProcessor:
        def __init__(self, **kwargs):
            captured.update(kwargs)

    monkeypatch.setattr("models.processors.LangflowFileProcessor", FakeProcessor)

    async def fake_create_custom_task(*args, **kwargs):
        return "task-id"

    svc = TaskService(docling_polling_service=injected)
    monkeypatch.setattr(svc, "create_custom_task", fake_create_custom_task)

    await svc.create_langflow_upload_task(
        user_id="u1",
        file_paths=["/tmp/x.pdf"],
        langflow_file_service=AsyncMock(),
        session_manager=AsyncMock(),
        allow_anonymous_delete=True,
    )

    assert captured["docling_polling_service"] is injected


@pytest.mark.asyncio
async def test_docling_submit_failure_skips_polling_and_langflow(
    mock_docling_service, mock_polling_service, file_tuple, file_task
):
    mock_docling_service.upload_to_docling_direct_async.side_effect = Exception(
        "docling unreachable"
    )
    svc = LangflowFileService(docling_service=mock_docling_service)
    svc.run_ingestion_flow = AsyncMock()

    with pytest.raises(Exception, match="Docling upload failed"):
        await svc.upload_and_ingest_file(
            file_tuple=file_tuple,
            docling_polling_service=mock_polling_service,
            file_task=file_task,
        )

    assert mock_polling_service.poll_until_ready.call_count == 0
    assert svc.run_ingestion_flow.call_count == 0
    assert file_task.docling_task_id is None