ExuluDocumentProcessor

ExuluDocumentProcessor converts documents to structured markdown for ingestion into knowledge contexts. It supports multiple processor backends — docling (Python, best for complex PDFs), liteparse (JS, broad format support), mistral (OCR via LiteLLM proxy), and officeparser (JS, Office formats) — and optionally validates and corrects each page using a VLM pass. The advanced-document-processing EE entitlement is checked at runtime; calling process without a valid license throws immediately.

API surface

ExuluDocumentProcessor.process

ExuluDocumentProcessor.process(opts: {
  file: string | Buffer;
  name: string;
  config?: DocumentProcessorConfig;
}): Promise<ProcessedDocument | undefined>

Processes a document and returns an array of per-page objects with the extracted markdown content.

string | Buffer

required

The document to process. Pass a local file path, an HTTP/HTTPS URL (downloaded automatically), or a Buffer with the raw file bytes.

string

required

The file name including extension (e.g. "report.pdf"). The extension determines which code path handles the file; it is required even when file is a Buffer.

"docling" | "liteparse" | "mistral" | "officeparser"

required

The processing backend to use.

string

LiteLLM model_name for the "mistral" OCR backend. Defaults to "mistral-ocr".

number

Maximum pages per OCR request for the "mistral" backend. Defaults to 25 (safely below the 30-page Vertex AI limit). The PDF is split into chunks of this size before sending.Byte-size bisection: in addition to the page limit, each chunk is enforced to stay under 25 MB on disk. Chunks that exceed this byte limit and contain more than one page are deleted and recursively re-split by bisecting the page range until every chunk fits. Single-page chunks that still exceed 25 MB are kept with a stderr warning — they cannot be split further without re-encoding. This logic is implemented in ee/python/documents/processing/split_pdf.py and is invoked with --max-size-mb 25 from the document-processor pipeline.

string

LiteLLM model_name for the optional VLM validation pass (e.g. "vertex-gemini-2.5-flash"). Only supported when processor.name is "docling". When set, pages containing tables or images are re-validated and corrected by the VLM.

number

Number of pages to validate in parallel. Required when vlm.model is set.

object

Optional cost-attribution fields (user, role, project, agent, routine, context) forwarded to LiteLLM as spend tags for both OCR and VLM passes.

boolean

Set to false to keep the per-job temp directory on disk after processing. Defaults to true.

Promise<ProcessedDocument | undefined>

ProcessedDocument is Array<{ page: number; content: string }>. Each element is one page of the document, with final content (VLM-corrected when applicable).

Supported file types by processor

Processor	Supported extensions
`docling`	`.pdf`, `.docx`, `.doc`, `.txt`, `.md`, `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
`liteparse`	`.pdf`, `.doc`, `.docx`, `.docm`, `.odt`, `.rtf`, `.ppt`, `.pptx`, `.pptm`, `.odp`, `.xls`, `.xlsx`, `.xlsm`, `.ods`, `.csv`, `.tsv`
`mistral`	`.pdf`, `.docx`, `.doc`, `.txt`, `.md`, `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
`officeparser`	`.docx`, `.pptx`, `.xlsx`, `.odt`, `.odp`, `.ods`, `.pdf`, `.rtf`, `.csv`, `.md`, `.html`

Example

import { ExuluDocumentProcessor } from "@exulu/backend";
import { readFileSync } from "fs";

const buffer = readFileSync("./technical-manual.pdf");

const pages = await ExuluDocumentProcessor.process({
  file: buffer,
  name: "technical-manual.pdf",
  config: {
    processor: { name: "docling" },
    vlm: {
      model: "vertex-gemini-2.5-flash",
      concurrency: 5,
    },
  },
});

if (pages) {
  const fullText = pages.map((p) => p.content).join("\n\n");
  console.log(`Processed ${pages.length} pages`);
}

Notes

The docling backend runs Python and sets up a virtual environment automatically on first use via ExuluPython.setup. Python 3.10+ is required.
Pages are separated by  comments in the markdown stream written to disk, but the returned ProcessedDocument array already splits them per page.
Temporary files are created under <cwd>/temp/<uuid>/ and deleted after each call unless debugging.deleteTempFiles is false.

ExuluPython: manage the Python environment required by docling.
Knowledge — pipeline: how processed documents feed into knowledge contexts.

Start

Tutorials

Recipes

Core classes

Reference

ExuluDocumentProcessor

API surface