DocQuery Documentation

When using DocQuery, be aware of the following constraints:

• Pre-trained models only: It uses zero-shot models and does not learn from your specific data.
• Supported file types: Currently supports images and PDFs (with or without embedded text). It does not support Word documents, emails, or spreadsheets.
• Output types: Only produces scalar text outputs (answers). It treats numbers and dates as strings and does not support table extraction.

To read HTML documents/webpages, install the [web] extension:

pip install docquery[web]

Note: This requires Chrome to be installed globally on your system as it uses webdriver-manager to manage the driver.

Example: Querying a live website

docquery scan "What is the #1 post's title?" https://news.ycombinator.com

If you encounter a ModuleNotFoundError when attempting to use the docquery command, it is likely because the CLI dependencies were not included in your installation. You can install the package with the necessary CLI support using the following command:

pip install 'docquery[cli]'

DocQuery provides two main abstractions for programmatic use:

1. DocumentQuestionAnswering pipeline: Used to ask questions of documents.
2. Document abstraction: Used to load and parse various document types.

Example usage:

from docquery import document, pipeline

# Initialize the pipeline
p = pipeline('document-question-answering')

# Load a document
doc = document.load_document("/path/to/document.pdf")

# Ask multiple questions
for q in ["What is the invoice number?", "What is the invoice total?"]:
    print(q, p(question=q, **doc.context))

from docquery import document, pipeline
>>> p = pipeline('document-question-answering')
>>> doc = document.load_document("/path/to/document.pdf")
>>> for q in ["What is the invoice number?", "What is the invoice total?"]:
...     print(q, p(question=q, **doc.context))

To use the Donut model architecture, install the required extras:

pip install docquery[donut]

Example: Scanning with a specific Donut checkpoint

docquery scan "What is the effective date?" /path/to/contracts/folder --checkpoint 'naver-clova-ix/donut-base-finetuned-docvqa'

You can classify documents by adding the --classify flag to the scan command. You can specify a Hugging Face image classification model using the --checkpoint flag. By default, it uses Donut (which requires pip install docquery[donut]).

Example: Classify a folder of documents

docquery scan --classify /path/to/contracts/folder --checkpoint 'naver-clova-ix/donut-base-finetuned-docvqa'

Example: Classify documents and ask a question simultaneously

docquery scan --classify "What is the effective date?" /path/to/contracts/folder --checkpoint 'naver-clova-ix/donut-base-finetuned-docvqa'

Install the docquery library and CLI tool using pip:

pip install docquery

If you need to perform OCR on images, you must also install the tesseract system library:

• Mac OS X (Homebrew):

  brew install tesseract

• Ubuntu:

  apt install tesseract-ocr

To use DocQuery, you need to install the package along with its system dependencies for OCR and PDF processing.

1. Install tesseract-ocr for optical character recognition.
2. Install poppler-utils for PDF rendering.
3. Install the docquery package with the [all] extra to ensure all required components are present.

Note: The following commands assume a Linux-based environment (like Google Colab).

!sudo apt install tesseract-ocr
!sudo apt-get install poppler-utils
!pip install .[all]

When calling the DocumentClassificationPipeline, you can pass several parameters to control preprocessing and postprocessing behavior via **kwargs.

Preprocessing Parameters

• doc_stride: (int) The stride for document chunking.
• max_seq_len: (int) The maximum sequence length.
• lang: (str) Language for OCR (Tesseract).
• tesseract_config: (str) Configuration string for Tesseract.
• max_num_spans: (int) Maximum number of spans to process.

Postprocessing Parameters

• function_to_apply: (str or ClassificationFunction) The function to apply to logits (e.g., "sigmoid", "softmax", or "none").
• top_k: (int) The number of top labels to return. Must be $\ge 1$.

The LayoutLMForQuestionAnswering model supports three additional configuration parameters that are not present in the mainline transformers implementation. These parameters allow you to control an additional token classification head used during training:

• token_classification (bool, defaults to False): Whether to include an additional token classification head in question answering.
• token_classifier_reduction (str, defaults to "mean"): Specifies the reduction applied to the output of the cross entropy loss for the token classifier head. Valid options are: 'none', 'mean', or 'sum'.
• token_classifier_constant (float, defaults to 1.0): A coefficient for the token classifier head's contribution to the total loss. Increasing this value prioritizes learning the token classifier head during training.

If an OCR engine is requested but not installed on the system, the library raises a NoOCRReaderFound exception.

• Tesseract: Requires pytesseract and the Tesseract binary installed on your system.
• EasyOCR: Requires the easyocr Python package.

If no OCR engines are found and no specific engine is requested, the system may fall back to a DummyOCRReader which logs a warning.

If load_document() encounters a file type it cannot process or a download failure, it raises an UnsupportedDocument exception.

Additionally, certain PDF features depend on external libraries:

• If pdf2image is not installed, OCR will be unavailable for PDFs.
• If pdfplumber is not installed, PDF processing will fail.