[Task] Resolve PDF Text Extraction Failure on Scanned/Image-Only Documents

[knoxiboy]

Title: [BUG] Resolve PDF Text Extraction Failure on Scanned/Image-Only Documents

Is your feature request related to a problem? Please describe.

When users upload scanned PDFs (e.g., scanned invoices or printed documents saved as PDF images), PyMuPDF extracts 0 characters of text. As a result, the ingestion task creates empty text chunks, and the document cannot be searched or queried.

Describe the solution you'd like

Implement automated OCR fallback:

1. Integrate an OCR library (e.g., pytesseract or easyocr) into the parser service.
2. In backend/app/rag/chunker.py, check if the total extracted text character count is below a threshold (e.g. 50 characters).
3. If below threshold, convert the PDF pages to images and run OCR to extract text before chunking.
4. Ensure appropriate system dependencies (like tesseract-ocr) are documented or added to the Dockerfile.

Describe alternatives you've considered

Rejecting scanned files, but users expect all PDF documents to work seamlessly in a document analysis platform.

Additional Context

• GSSoC '26: Yes, I am participating in GirlScript Summer of Code and would like to build this.
• Level: Critical
• Affected Files: backend/app/rag/chunker.py, Dockerfile, backend/requirements.txt

[github-actions]

Hi @knoxiboy! 👋

Thanks for opening this issue! We are thrilled to have you contribute to PDF-Assistant-RAG for GSSoC 2026.

📌 Before you start:

• Make sure you have read our Contributing Guidelines.
• Wait for a project admin to assign this issue to you before working on it.
• Remember to branch off dev and not main.

Happy Coding! 🚀

[knoxiboy]

/assign gssoc'26

@param20h Please assign this issue to me under gssoc'26

[virakshi07]

Hello @knoxiboy 👋,

I would like to work on this issue under GSSoC 2026.

After reviewing the issue, I understand that the current document ingestion pipeline relies primarily on text extraction from PDFs. While this works well for digitally generated PDFs, it fails when users upload scanned or image-only documents because these files contain visual text rather than embedded text layers. As a result, the extraction process returns little or no content, causing downstream chunking, indexing, and retrieval operations to fail.

This is a critical usability issue because users generally expect all PDFs—whether digitally generated or scanned—to be searchable and analyzable within the platform.

---

📄 Problem Analysis

Current Processing Flow

PDF Upload
      │
      ▼
PyMuPDF Text Extraction
      │
      ▼
Extracted Text
      │
      ▼
Chunking
      │
      ▼
Vector Store

For scanned PDFs:

PDF Upload
      │
      ▼
PyMuPDF
      │
      ▼
0 Characters Extracted
      │
      ▼
Empty Chunks
      │
      ▼
Failed Search & Retrieval

The pipeline assumes that every PDF contains selectable text, which is not true for scanned documents.

---

🎯 Objective

Enhance the ingestion workflow by introducing an OCR fallback mechanism that automatically detects image-based PDFs and extracts text using Optical Character Recognition before chunking and indexing.

The solution should work transparently without requiring additional actions from the user.

---

🏗️ Proposed Implementation Plan

Phase 1 — Analyze Current Pipeline

Review:

backend/app/rag/chunker.py

and related ingestion modules to understand:

• Current PDF parsing workflow
• Text extraction logic
• Chunk generation process
• Error handling mechanisms

This will help integrate OCR cleanly without disrupting existing functionality.

---

🔍 Phase 2 — Detection Mechanism

Before triggering OCR, implement a lightweight validation step.

Example:

if len(extracted_text.strip()) < OCR_THRESHOLD:
    run_ocr = True

Potential threshold:

OCR_THRESHOLD = 50

This prevents OCR from running unnecessarily on valid PDFs.

---

🧠 Phase 3 — OCR Integration

Evaluate suitable OCR solutions such as:

Option A

pytesseract

Advantages:

• Mature ecosystem
• Strong language support
• Easy integration

---

Option B

easyocr

Advantages:

• Deep learning based
• Better performance on noisy scans
• Multi-language support

I will select the option that best aligns with the project's requirements and deployment environment.

---

🖼️ Phase 4 — PDF-to-Image Conversion

When OCR fallback is triggered:

PDF
   ↓
Page Images
   ↓
OCR Engine
   ↓
Extracted Text

Potential tools:

PyMuPDF
pdf2image
Pillow

depending on existing project dependencies.

---

📚 Phase 5 — Text Consolidation

Combine OCR output across pages:

Page 1 OCR
+
Page 2 OCR
+
Page 3 OCR

into a unified text document before:

Chunking
Embedding
Indexing

This preserves compatibility with the existing RAG pipeline.

---

🧪 Testing Strategy

Test Case 1

Standard PDF

Embedded Text PDF

Expected:

Normal Extraction
No OCR Triggered

---

Test Case 2

Fully Scanned PDF

Image-Only PDF

Expected:

OCR Activated
Text Extracted
Chunks Generated

---

Test Case 3

Mixed PDF

Some Pages Text
Some Pages Scanned

Expected:

Accurate Content Extraction

---

Test Case 4

Empty PDF

Expected:

Graceful Failure Handling

---

Test Case 5

Large Multi-Page Document

Expected:

Successful OCR Processing
Stable Memory Usage

---

🐳 Deployment & Dependency Updates

I will ensure all required dependencies are properly configured.

Potential updates:

Requirements

backend/requirements.txt

Container Setup

Dockerfile

Documentation

Setup Instructions
Installation Notes
OCR Requirements

This ensures contributors can run the feature locally without additional troubleshooting.

---

⚡ Performance Considerations

Because OCR can be computationally expensive, I will ensure:

OCR Runs Only When Necessary

Low Extracted Text
      ↓
OCR

Valid PDFs Skip OCR

Text Found
      ↓
Normal Pipeline

This minimizes unnecessary processing overhead.

---

🚀 Future Extensibility

The architecture could later support:

Multi-Language OCR

English
Spanish
French
Hindi
etc.

Handwritten Text Recognition

Advanced Document Classification

OCR Confidence Scoring

without requiring major changes to the ingestion workflow.

---

🎯 Expected Outcome

✅ Automatic support for scanned PDFs

✅ OCR fallback for image-only documents

✅ Improved document ingestion success rate

✅ Searchable scanned documents

✅ Better RAG retrieval quality

✅ Backward compatibility with existing PDFs

✅ Updated dependencies and documentation

✅ Improved overall user experience

---

Why I Would Like To Work On This Issue

I am particularly interested in document processing, RAG systems, OCR pipelines, and backend AI workflows. This issue is impactful because it directly improves the platform's ability to handle real-world documents, where scanned PDFs are extremely common.

I would carefully analyze the existing ingestion pipeline, implement an efficient OCR fallback mechanism, ensure compatibility with the current architecture, and provide proper testing and documentation for long-term maintainability.

I would be excited to contribute this enhancement to the project.

Kindly assign this issue to me.

Thank you for your time and consideration! 🚀

/assign