Skip to content

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

Python

Make docling optional and add graceful handling

Edwin Josea2a852efdc97
diff --git a/pyproject.toml b/pyproject.toml
index 95df66893..394652a86 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,8 +12,6 @@ dependencies = [
"agentd>=0.2.2",
"aiofiles>=24.1.0",
"cryptography>=45.0.6",
- "docling[vlm]==2.41.0; sys_platform != 'darwin'",
- "docling[ocrmac,vlm]==2.41.0; sys_platform == 'darwin'",
"google-api-python-client>=2.143.0",
"google-auth-httplib2>=0.2.0",
"google-auth-oauthlib>=1.2.0",
@@ -33,9 +31,15 @@ dependencies = [
"textual-fspicker>=0.6.0",
"structlog>=25.4.0",
"docling-serve==1.5.0",
+ "zxcvbn>=4.5.0"
+]
+
+[project.optional-dependencies]
+docling = [
+ "docling[vlm]==2.41.0; sys_platform != 'darwin'",
+ "docling[ocrmac,vlm]==2.41.0; sys_platform == 'darwin'",
"docling-core==2.48.1",
"easyocr>=1.7.1; sys_platform != 'darwin'",
- "zxcvbn>=4.5.0"
]
[dependency-groups]
diff --git a/src/api/upload.py b/src/api/upload.py
index 3eab9b4c4..835a1e8f7 100644
--- a/src/api/upload.py
+++ b/src/api/upload.py
@@ -35,6 +35,13 @@ async def upload(request: Request, document_service, session_manager):
)
return JSONResponse(result, status_code=201) # Created
except Exception as e:
+ from utils.document_processing import DoclingNotInstalledError
+
+ if isinstance(e, DoclingNotInstalledError):
+ return JSONResponse(
+ {"error": str(e), "detail": "Install openrag[docling] or use Langflow for ingestion."},
+ status_code=503,
+ )
error_msg = str(e)
if (
"AuthenticationException" in error_msg
@@ -109,7 +116,17 @@ async def upload_context(
jwt_token = session_manager.get_effective_jwt_token(user_id, request.state.jwt_token)
# Process document and extract content
- doc_result = await document_service.process_upload_context(upload_file, filename)
+ try:
+ doc_result = await document_service.process_upload_context(upload_file, filename)
+ except Exception as e:
+ from utils.document_processing import DoclingNotInstalledError
+
+ if isinstance(e, DoclingNotInstalledError):
+ return JSONResponse(
+ {"error": str(e), "detail": "Install openrag[docling] for PDF/image context or use .txt files."},
+ status_code=503,
+ )
+ raise
# Send document content as user message to get proper response_id
response_text, response_id = await chat_service.upload_context_chat(
diff --git a/src/config/settings.py b/src/config/settings.py
index f9118bc46..2b161446a 100644
--- a/src/config/settings.py
+++ b/src/config/settings.py
@@ -11,7 +11,6 @@ from opensearchpy import AsyncOpenSearch
from opensearchpy._async.http_aiohttp import AIOHttpConnection
from utils.container_utils import get_container_host
-from utils.document_processing import create_document_converter
from utils.logging_config import get_logger
load_dotenv(override=False)
@@ -308,7 +307,16 @@ class AppClients:
self.langflow_http_client = None
self._patched_async_client = None # Private attribute - single client for all providers
self._client_init_lock = __import__('threading').Lock() # Lock for thread-safe initialization
- self.converter = None
+ self._converter = None
+
+ @property
+ def converter(self):
+ """Lazy-init document converter (requires openrag[docling]). Raises DoclingNotInstalledError if not installed."""
+ if self._converter is None:
+ from utils.document_processing import create_document_converter
+
+ self._converter = create_document_converter(ocr_engine=DOCLING_OCR_ENGINE)
+ return self._converter
async def initialize(self):
# Initialize OpenSearch client
@@ -333,8 +341,7 @@ class AppClients:
else:
logger.info("OpenAI API key not found in environment - will be initialized on first use if needed")
- # Initialize document converter
- self.converter = create_document_converter(ocr_engine=DOCLING_OCR_ENGINE)
+ # Document converter is lazy-initialized on first access (requires openrag[docling] for local ingestion)
# Initialize Langflow HTTP client with extended timeouts for large documents
# Must be created before wait_for_langflow / get_langflow_api_key
diff --git a/src/main.py b/src/main.py
index 7de3c13b3..64c10232d 100644
--- a/src/main.py
+++ b/src/main.py
@@ -1588,6 +1588,17 @@ async def create_app():
app.state.services = services # Store services for cleanup
app.state.background_tasks = set()
+ # Return 503 when docling is required but openrag[docling] is not installed
+ from utils.document_processing import DoclingNotInstalledError
+
+ async def docling_not_installed_handler(request, exc):
+ return JSONResponse(
+ {"error": str(exc), "detail": "Install openrag[docling] or use Langflow for ingestion."},
+ status_code=503,
+ )
+
+ app.add_exception_handler(DoclingNotInstalledError, docling_not_installed_handler)
+
# Add startup event handler
@app.on_event("startup")
async def startup_event():
diff --git a/src/models/processors.py b/src/models/processors.py
index 9c857a0b9..6386a52af 100644
--- a/src/models/processors.py
+++ b/src/models/processors.py
@@ -217,7 +217,16 @@ class TaskProcessor:
if original_filename:
slim_doc["filename"] = original_filename
else:
- # Convert and extract using docling for other file types
+ # Convert and extract using docling for other file types (requires openrag[docling])
+ from utils.document_processing import (
+ DoclingNotInstalledError,
+ is_docling_available,
+ )
+
+ if not is_docling_available():
+ raise DoclingNotInstalledError(
+ "Local ingestion requires openrag[docling]. Use Langflow ingestion or install the docling extra."
+ )
result = clients.converter.convert(file_path)
full_doc = result.document.export_to_dict()
slim_doc = extract_relevant(full_doc)
diff --git a/src/services/document_service.py b/src/services/document_service.py
index f010b6c5a..c9ab21a5f 100644
--- a/src/services/document_service.py
+++ b/src/services/document_service.py
@@ -4,7 +4,6 @@ import tempfile
import os
import aiofiles
from io import BytesIO
-from docling_core.types.io import DocumentStream
from typing import List
import openai
import tiktoken
@@ -210,7 +209,16 @@ class DocumentService:
"content_length": len(text_content),
}
else:
- # Create DocumentStream and process with docling
+ # Create DocumentStream and process with docling (requires openrag[docling])
+ from utils.document_processing import is_docling_available
+
+ if not is_docling_available():
+ from utils.document_processing import DoclingNotInstalledError
+ raise DoclingNotInstalledError(
+ "Docling is not installed. Install openrag[docling] for PDF/image context uploads or use .txt files."
+ )
+ from docling_core.types.io import DocumentStream
+
doc_stream = DocumentStream(name=filename, stream=content)
result = clients.converter.convert(doc_stream)
full_doc = result.document.export_to_dict()
diff --git a/src/utils/document_processing.py b/src/utils/document_processing.py
index 9619cf74a..dfc05ebd6 100644
--- a/src/utils/document_processing.py
+++ b/src/utils/document_processing.py
@@ -11,6 +11,27 @@ logger = get_logger(__name__)
# Global converter cache for worker processes
_worker_converter = None
+DOCLING_NOT_INSTALLED_MESSAGE = (
+ "Docling is not installed. Install with: pip install openrag[docling] "
+ "or use Langflow for ingestion (default)."
+)
+
+
+class DoclingNotInstalledError(ImportError):
+ """Raised when docling-based processing is used but the docling extra is not installed."""
+
+ def __init__(self, message: str | None = None):
+ super().__init__(message or DOCLING_NOT_INSTALLED_MESSAGE)
+
+
+def is_docling_available() -> bool:
+ """Return True if the docling package can be imported (openrag[docling] installed)."""
+ try:
+ from docling.document_converter import DocumentConverter # noqa: F401
+ return True
+ except ImportError:
+ return False
+
def create_document_converter(ocr_engine: str | None = None):
"""Create a Docling DocumentConverter with OCR disabled unless requested."""
@@ -24,13 +45,17 @@ def create_document_converter(ocr_engine: str | None = None):
PdfFormatOption,
)
from docling.datamodel.pipeline_options import PdfPipelineOptions
+ except ImportError:
+ raise DoclingNotInstalledError()
except Exception as exc: # pragma: no cover - fallback path
logger.debug(
"Falling back to default DocumentConverter import",
error=str(exc),
)
- from docling.document_converter import DocumentConverter # type: ignore
-
+ try:
+ from docling.document_converter import DocumentConverter # type: ignore
+ except ImportError:
+ raise DoclingNotInstalledError()
return DocumentConverter()
pipeline_options = PdfPipelineOptions()
@@ -84,8 +109,9 @@ def create_document_converter(ocr_engine: str | None = None):
def get_worker_converter():
"""Get or create a DocumentConverter instance for this worker process"""
global _worker_converter
+ if not is_docling_available():
+ raise DoclingNotInstalledError()
if _worker_converter is None:
-
# Configure GPU settings for this worker
has_gpu_devices, _ = detect_gpu_devices()
if not has_gpu_devices:
diff --git a/warm_up_docling.py b/warm_up_docling.py
index 3a834e2f6..d21fbe265 100644
--- a/warm_up_docling.py
+++ b/warm_up_docling.py
@@ -7,11 +7,17 @@ src_path = os.path.join(repo_root, "src")
if src_path not in sys.path:
sys.path.insert(0, src_path)
-from utils.document_processing import create_document_converter
-
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
+from utils.document_processing import is_docling_available
+
+if not is_docling_available():
+ logger.info("Docling not installed, skipping warm-up")
+ sys.exit(0)
+
+from utils.document_processing import create_document_converter
+
logger.info("Warming up docling models")
try: