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.tomlindex 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.pyindex 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) # Createdexcept 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_idresponse_text, response_id = await chat_service.upload_context_chat(diff --git a/src/config/settings.py b/src/config/settings.pyindex f9118bc46..2b161446a 100644--- a/src/config/settings.py+++ b/src/config/settings.py@@ -11,7 +11,6 @@ from opensearchpy import AsyncOpenSearchfrom opensearchpy._async.http_aiohttp import AIOHttpConnectionfrom utils.container_utils import get_container_host-from utils.document_processing import create_document_converterfrom utils.logging_config import get_loggerload_dotenv(override=False)@@ -308,7 +307,16 @@ class AppClients:self.langflow_http_client = Noneself._patched_async_client = None # Private attribute - single client for all providersself._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._converterasync 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_keydiff --git a/src/main.py b/src/main.pyindex 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 cleanupapp.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.pyindex 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_filenameelse:- # 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.pyindex f010b6c5a..c9ab21a5f 100644--- a/src/services/document_service.py+++ b/src/services/document_service.py@@ -4,7 +4,6 @@ import tempfileimport osimport aiofilesfrom io import BytesIO-from docling_core.types.io import DocumentStreamfrom typing import Listimport openaiimport 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.pyindex 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 pathlogger.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 workerhas_gpu_devices, _ = detect_gpu_devices()if not has_gpu_devices:diff --git a/warm_up_docling.py b/warm_up_docling.pyindex 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: