Skip to content

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

Python

fix: Match handling of ingest of image only doc w/o langflow (#2308)

Mike Fortman760408dc3384
diff --git a/src/models/processors.py b/src/models/processors.py
index 3359cf747..2287dd813 100644
--- a/src/models/processors.py
+++ b/src/models/processors.py
@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any, Literal
from config.settings import clients, get_embedding_model, get_index_name, get_openrag_config
from session_manager import AnonymousUser
from utils.document_processing import (
+ IMAGE_PLACEHOLDER,
extract_relevant,
process_text_file,
resplit_chunks_character_windows,
@@ -531,6 +532,18 @@ class TaskProcessor:
# since chunk_texts_for_embeddings also drops empty texts.
slim_doc["chunks"] = [c for c in slim_doc["chunks"] if c.get("text") and c["text"].strip()]
+ # A placeholder preserves picture provenance for otherwise empty documents,
+ # but it is not searchable content and must not turn ingestion into a false
+ # success or consume an embedding request.
+ if slim_doc["chunks"] and all(
+ chunk["text"].strip() == IMAGE_PLACEHOLDER for chunk in slim_doc["chunks"]
+ ):
+ logger.error(
+ "No searchable content extracted — document contains only image placeholders",
+ file_hash=file_hash,
+ )
+ return {"status": "error", "error": "No text content could be extracted from document"}
+
litellm_embedding_model = (
await self.models_service.get_litellm_model_name(embedding_model)
if self.models_service is not None
diff --git a/src/utils/document_processing.py b/src/utils/document_processing.py
index af2b65706..955ed2b46 100644
--- a/src/utils/document_processing.py
+++ b/src/utils/document_processing.py
@@ -5,6 +5,8 @@ from utils.logging_config import get_logger
logger = get_logger(__name__)
+IMAGE_PLACEHOLDER = "<!-- image -->"
+
def process_text_file(file_path: str) -> dict:
"""
@@ -82,6 +84,8 @@ def extract_relevant(doc_dict: dict) -> dict:
- Finds every text fragment in `texts`, groups them by page_no
- Flattens tables in `tables` into tab-separated text, grouping by row
- Concatenates each page's fragments and each table into its own chunk
+ - Emits a picture chunk for each picture with description annotations
+ - Emits one image placeholder only when pictures exist and no other chunks were produced
Returns a slimmed dict ready for indexing, with each chunk under "text".
"""
origin = doc_dict.get("origin", {})
@@ -136,7 +140,8 @@ def extract_relevant(doc_dict: dict) -> dict:
# Without this, image-only documents (no text layer) yield zero chunks on the
# non-Langflow path, which surfaces as a misleading "corrupted or invalid" error.
# The Langflow path already captures them via Docling's export_to_markdown.
- for p_idx, picture in enumerate(doc_dict.get("pictures", [])):
+ pictures = doc_dict.get("pictures", [])
+ for p_idx, picture in enumerate(pictures):
prov = picture.get("prov", [])
page_no = prov[0].get("page_no") if prov else None
if page_no is None:
@@ -147,15 +152,28 @@ def extract_relevant(doc_dict: dict) -> dict:
for ann in picture.get("annotations", [])
if ann.get("kind") == "description" and ann.get("text", "").strip()
]
- if not descriptions:
- continue
+ if descriptions:
+ chunks.append(
+ {
+ "page": page_no,
+ "type": "picture",
+ "picture_index": p_idx,
+ "text": "\n".join(descriptions),
+ }
+ )
+ # Preserve a non-empty signal for image-only documents without descriptions,
+ # but avoid embedding one identical placeholder for every uncaptioned picture.
+ if not chunks and pictures:
+ first_picture = pictures[0]
+ prov = first_picture.get("prov", [])
+ page_no = prov[0].get("page_no") if prov else None
chunks.append(
{
- "page": page_no,
+ "page": page_no if page_no is not None else 1,
"type": "picture",
- "picture_index": p_idx,
- "text": "\n".join(descriptions),
+ "picture_index": 0,
+ "text": IMAGE_PLACEHOLDER,
}
)
diff --git a/tests/unit/test_extract_relevant_pictures.py b/tests/unit/test_extract_relevant_pictures.py
index 2b3b278a5..d30055a50 100644
--- a/tests/unit/test_extract_relevant_pictures.py
+++ b/tests/unit/test_extract_relevant_pictures.py
@@ -45,8 +45,8 @@ def test_multiple_descriptions_joined():
assert chunk["page"] == 3
-def test_classification_only_annotation_is_skipped():
- """Non-description annotations (e.g. classification) carry no caption text."""
+def test_classification_only_annotation_yields_placeholder():
+ """Non-description annotations (e.g. classification) produce an image placeholder."""
doc = {
"origin": {},
"pictures": [
@@ -62,18 +62,41 @@ def test_classification_only_annotation_is_skipped():
}
],
}
- assert extract_relevant(doc)["chunks"] == []
+ chunks = extract_relevant(doc)["chunks"]
+ assert len(chunks) == 1
+ assert chunks[0]["text"] == "<!-- image -->"
+ assert chunks[0]["page"] == 1
-def test_empty_or_whitespace_description_skipped():
+def test_uncaptioned_pictures_do_not_add_placeholders_when_content_exists():
doc = {
"origin": {},
+ "texts": [{"prov": [{"page_no": 1}], "text": "body text"}],
"pictures": [
{"prov": [{"page_no": 1}], "annotations": [_description(" ")]},
{"prov": [{"page_no": 2}], "annotations": []},
],
}
- assert extract_relevant(doc)["chunks"] == []
+ chunks = extract_relevant(doc)["chunks"]
+ assert len(chunks) == 1
+ assert chunks[0]["type"] == "text"
+ assert chunks[0]["text"] == "body text"
+
+
+def test_uncaptioned_image_only_doc_yields_one_placeholder():
+ doc = {
+ "origin": {},
+ "pictures": [
+ {"prov": [{"page_no": 2}], "annotations": [_description(" ")]},
+ {"prov": [{"page_no": 3}], "annotations": []},
+ ],
+ }
+ chunks = extract_relevant(doc)["chunks"]
+ assert len(chunks) == 1
+ assert chunks[0]["type"] == "picture"
+ assert chunks[0]["text"] == "<!-- image -->"
+ assert chunks[0]["page"] == 2
+ assert chunks[0]["picture_index"] == 0
def test_missing_prov_defaults_to_page_one():
diff --git a/tests/unit/test_processors_image_only.py b/tests/unit/test_processors_image_only.py
new file mode 100644
index 000000000..e971beacd
--- /dev/null
+++ b/tests/unit/test_processors_image_only.py
@@ -0,0 +1,75 @@
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from models.processors import TaskProcessor
+
+
+async def test_placeholder_only_document_returns_no_text_error_before_embedding(monkeypatch):
+ embedding_create = AsyncMock(side_effect=AssertionError("placeholder must not be embedded"))
+ monkeypatch.setattr(
+ "models.processors.clients",
+ SimpleNamespace(
+ opensearch=None,
+ patched_embedding_client=SimpleNamespace(
+ embeddings=SimpleNamespace(create=embedding_create)
+ ),
+ ),
+ )
+ monkeypatch.setattr(
+ "models.processors.get_openrag_config",
+ lambda: SimpleNamespace(
+ knowledge=SimpleNamespace(
+ embedding_model="text-embedding-3-small",
+ chunk_size=None,
+ chunk_overlap=None,
+ )
+ ),
+ )
+ monkeypatch.setattr(
+ "services.document_service.chunk_texts_for_embeddings",
+ lambda texts, max_tokens: [texts],
+ )
+
+ user_client = SimpleNamespace()
+ document_service = SimpleNamespace(
+ session_manager=SimpleNamespace(
+ get_user_opensearch_client=lambda user_id, jwt_token: user_client
+ )
+ )
+ models_service = SimpleNamespace(
+ get_litellm_model_name=AsyncMock(return_value="text-embedding-3-small")
+ )
+ docling_service = SimpleNamespace(
+ convert_file=AsyncMock(
+ return_value={
+ "origin": {
+ "binary_hash": "image-hash",
+ "filename": "scan.png",
+ "mimetype": "image/png",
+ },
+ "texts": [],
+ "tables": [],
+ "pictures": [{"prov": [{"page_no": 1}], "annotations": []}],
+ }
+ )
+ )
+ processor = TaskProcessor(document_service, models_service, docling_service)
+ processor.check_document_exists = AsyncMock(return_value=False)
+
+ result = await processor.process_document_standard(
+ file_path="scan.png",
+ file_hash="image-hash",
+ owner_user_id="user-1",
+ jwt_token="Bearer token",
+ ocr=False,
+ picture_descriptions=False,
+ )
+
+ assert result == {
+ "status": "error",
+ "error": "No text content could be extracted from document",
+ }
+ embedding_create.assert_not_awaited()
diff --git a/tests/unit/test_task_service_get_task_status2.py b/tests/unit/test_task_service_get_task_status2.py
index 1ae2bb850..7ef0516ed 100644
--- a/tests/unit/test_task_service_get_task_status2.py
+++ b/tests/unit/test_task_service_get_task_status2.py
@@ -159,6 +159,22 @@ class TestInferFailureMetadata:
assert meta is not None
assert meta["actionable_by"] == "USER_ACTIONABLE"
+ def test_image_without_text_prompts_user_to_enable_ocr(self, task_service):
+ ft = _make_file_task(
+ file_path="scan.png",
+ filename="scan.png",
+ error="No text content could be extracted from document",
+ )
+
+ meta = task_service._infer_failure_metadata(ft)
+
+ assert meta is not None
+ assert meta["actionable_by"] == "RETRYABLE"
+ assert meta["user_facing_message"] == (
+ "No text content could be extracted from this image file. "
+ "Enable OCR in Settings > Knowledge Base and retry ingestion."
+ )
+
def test_docling_phase_still_processing(self, task_service):
ft = _make_file_task(
phase=IngestionPhase.DOCLING,