Document Ingestion & OCR

Relevant source files

The following files were used as context for generating this wiki page:

• ingestion.py
• pipeline.py
• backend.py
• security.py
• parsing/parser.py
• requirements.txt

The Document Ingestion & OCR system serves as the entry point for the Rosy tax processing pipeline. Its primary purpose is to transform various input formats—including digital PDFs, scanned images (PNG, JPG), and plain text files—into a unified string format that can be consumed by downstream classification and extraction modules.

This system handles file validation, optical character recognition (OCR) for non-digital media, and text extraction for digital documents. By providing a normalized text output, it abstracts the complexity of different file formats away from the core tax logic.
Sources: ingestion.py:1-7, pipeline.py:1-6, README.md:12-14

System Architecture & Data Flow

The ingestion process is triggered when a user uploads files via the web interface or CLI. The backend.py module handles the initial upload, applying security constraints before passing file paths to the pipeline.

The diagram above illustrates the path from initial upload through the multi-format handling in the ingestion module.
Sources: backend.py:59-80, ingestion.py:20-80, pipeline.py:18-35

Ingestion Components

File Validation and Security

Before processing, files undergo sanitization and validation to prevent path traversal and resource exhaustion.

Feature	Description	Constraint
Filename Sanitization	Removes dangerous characters and limits length.	200 character limit
Type Validation	Restricts uploads to specific extensions.	.pdf, .txt, .png, .jpg, .jpeg
Size Limits	Prevents processing of excessively large files.	5 MB per file

Sources: security.py:10-30, backend.py:65-72

Multi-Format Processing Logic

The ingest_paths function in ingestion.py acts as the orchestrator for reading different file types. It employs a "lazy import" strategy for heavy dependencies like PIL (Pillow), pytesseract, and pdf_reader to allow the system to function in environments where OCR tools might be missing.

• PDF Extraction: Attempts to extract embedded text using pdf_reader.
• OCR (Optical Character Recognition): For images (.png, .jpg, .jpeg, etc.), the system utilizes pytesseract to convert visual data into text.
• Direct Reading: Text files (.txt) are read directly as UTF-8 encoded strings.

Sources: ingestion.py:20-55, requirements.txt:6-12

Sequence of Operations

The following sequence diagram details the interaction between the API, the pipeline, and the ingestion helper.

Implementation Details

Ingestion Logic

The core logic for handling multiple paths and consolidating their content is found in ingestion.py.

# ingestion.py:20-33
def ingest_paths(paths: List[str]) -> str:
    """Given a list of file paths (images or text), return combined OCR/text content."""
    texts = []
    # ... lazy imports of PIL and pytesseract ...
    for p in paths:
        p = os.path.abspath(p)
        ext = os.path.splitext(p)[1].lower()
        
        if ext == '.txt':
            texts.append(read_text_file(p))
        elif ext == '.pdf':
            # handle pdf...
        elif ext in ['.png', '.jpg', '.jpeg']:
            # handle OCR...
    return "\n".join(texts)

Sources: ingestion.py:20-80

Error Handling & Dependencies

The system includes fallback mechanisms and descriptive error messages for missing system-level dependencies. If Tesseract is not installed on the host machine, the system raises a RuntimeError with installation instructions.

Dependency	Purpose	Optional?
pytesseract	OCR engine for images	Yes (required for images)
Pillow	Image loading and manipulation	Yes (required for images)
PyMuPDF	PDF text extraction	Yes (required for PDFs)

Sources: ingestion.py:58-75, requirements.txt:6-14

Summary

The Document Ingestion & OCR module provides a robust entry point for tax document processing. By abstracting the complexities of OCR and PDF parsing into a single ingest_paths interface, it ensures that the rest of the Rosy system can operate on clean, structured text regardless of the original source format. This modularity allows for the system to be deployed in both minimal environments (processing text files) and full-featured environments (processing scanned tax forms).