Layout Awareness

MariaDB AI RAG layout-aware extraction offers three tiers: fast base text extraction, local Docling structure preservation with OCR, and cloud LlamaParse for complex multi-column PDFs.

When you upload a document (like a PDF) to an AI system, the system needs to read the text. Standard text extractors simply pull the words out left-to-right, top-to-bottom. This works fine for simple text, but it completely destroys the structure of complex documents—tables become jumbled messes of words, headings are lost, and mathematical formulas become unreadable.

Layout-Aware Extraction solves this by intelligently analyzing the visual structure of the document before reading it.

Instead of just extracting raw text, layout-aware processors convert your document into beautifully structured Markdown format. This means:

• Tables remain perfectly aligned and formatted (with rows/columns intact).

• Headings (H1, H2, H3) and reading order are preserved.

• Lists and bullet points stay intact.

• Code blocks and mathematical formulas are accurately captured.

Because the output is clean Markdown, our AI can chunk the document much more intelligently. By pairing this with chunking_method: "semantic", the system naturally splits the document along topical boundaries (headers), leading to vastly superior RAG (Retrieval-Augmented Generation) answers.

The three extraction tiers

The API offers three different processing tiers, which you can select when uploading documents via the processor_type parameter inside the document_processing JSON object.

Tier 1: Base

• Parameter: processor_type: "base"

• How it works: Fast, basic text extraction using libraries like pdfplumber and python-docx.

• Pros: Blazing fast, requires no special hardware, works entirely locally. Best for simple, text-heavy documents.

• Cons: Loses complex formatting; tables may be extracted poorly.

Tier 2: Layout-aware standard

• Parameter: processor_type: "layout_aware_standard"

• How it works: Uses the advanced open-source 'Docling' AI engine running locally on your hardware.

• Pros: Excellent preservation of tables, headings, and lists. Supports OCR (Optical Character Recognition) for scanned documents. Completely private and local (no data sent to the cloud).

• Cons: Slower than the base processor; can be CPU/memory intensive.

Tier 3: Layout-aware advanced

• Parameter: processor_type: "layout_aware_advanced"

• How it works: Sends the document to LlamaIndex's premium cloud API service (LlamaParse).

• Pros: The absolute highest quality extraction available. Incredible accuracy on highly complex, multi-column PDFs with dense tables.

• Cons: Requires an active internet connection, requires a paid API key from LlamaIndex, and documents leave your local network.

Layout Awareness Endpoints

To use advanced processing, you inject a document_processing JSON object into your ingestion API calls.

A. Manual File Upload Endpoint

Endpoint: POST /documents/ingest Purpose: Upload physical files from a user's computer to the API.

Since this is a multipart/form-data endpoint, the configuration must be passed as a stringified JSON object in the document_processing form field.

Form Data Example:

curl -X POST "http://localhost:8000/api/v1/documents/ingest" \
  -H "Authorization: Bearer <token>" \
  -F "files=@report2024.pdf" \
  -F "chunking_method=semantic" \
  -F 'document_processing={"processor_type": "layout_aware_standard", "enable_ocr": true, "enable_table_extraction": true}'

B. Cloud Storage / Orchestration Endpoint (Recommended)

Endpoint: POST /orchestrate/ingestion Purpose: Programmatically scan an S3/GCS bucket and ingest its contents using a specific processor.

This is a standard JSON endpoint, so you pass the configuration directly as an object.

JSON Payload Example:

{
  "chunking_method": "semantic",
  "chunk_size": 512,
  "cloud_storage_sources": [
    {
      "integration_id": "int_abc123",
      "prefix": "financial_reports/Q3/",
      "recursive": true,
      "file_extensions": [".pdf"]
    }
  ],
  "document_processing": {
    "processor_type": "layout_aware_standard",
    "enable_ocr": true,
    "ocr_provider": "rapidocr",
    "enable_table_extraction": true,
    "table_structure_mode": "accurate"
  }
}

Configuration schema options

Here is the complete reference for the document_processing JSON object.

Field	Type	Default	Description
processor_type	string	"base"	"base", "layout_aware_standard", or "layout_aware_advanced"

Settings for layout_aware_standard (Docling):

Field	Type	Default	Description
enable_ocr	bool	false	Turns on Optical Character Recognition for scanned images.
ocr_provider	string	"rapidocr"	Engine to use if OCR is enabled: "rapidocr" (fastest), "tesseract", "easyocr", or "surya" (state-of-the-art).
enable_table_extraction	bool	true	Preserves tables as markdown grids.
table_structure_mode	string	"accurate"	Table detection quality: "accurate" (better) or "fast".
enable_code_enrichment	bool	false	Specifically detect and format code blocks.
enable_formula_enrichment	bool	false	Specifically detect and format mathematical formulas.
enable_ray	bool	false	Use Ray cluster for distributed parallel processing of large PDFs.

Settings for layout_aware_advanced (LlamaParse):

Field	Type	Default	Description
llamaparse_preset	string	"agentic"	Quality tier: "cost_effective" ($0.003/page), "agentic" ($0.01/page), "agentic_plus" (~$0.03/page).

Layout-aware standard

Docling and Ray

The Standard tier uses IBM's Docling engine. Because Docling uses actual machine learning models to visually "read" the document layout, processing a 100-page PDF can take some time.

To solve this performance bottleneck, we integrated "Ray" — a framework for distributed computing.

How Ray Speeds Up Docling: Instead of processing a 100-page PDF sequentially (page 1, then page 2, then page 3...), Ray allows the system to split the document up and process multiple pages simultaneously across different CPU cores or even entirely different servers in a cluster.

Global Configuration Variables (config.env) to control Docling behavior when requested by the API:

• DOCLING_ENABLE_OCR=true : Enables OCR globally as default.

• DOCLING_OCR_PROVIDER=rapidocr : Global default engine used for OCR.

• DOCLING_RAY_ENABLED=true : Turns on parallel processing using Ray.

• DOCLING_RAY_NUM_ACTORS=4 : The number of parallel "workers" to spawn.

• DOCLING_RAY_HEAD_ADDRESS=auto : Set to 'auto' for local processing, or provide an IP address.

• DOCLING_RAY_SERVICE_URL=http://... : (Optional) URL to an external, dedicated Docling HTTP service.

Layout-aware advanced

LlamaParse

For enterprise users who need the absolute best accuracy and are willing to use a cloud API, we support LlamaParse.

Configuration Variables (config.env):

• LLAMA_CLOUD_API_KEY=llx-... : Your private API key from https://cloud.llamaindex.ai

LlamaParse Presets: You can control the quality vs. cost ratio of LlamaParse dynamically in the API payload using llamaparse_preset or globally via the LLAMAPARSE_PRESET env variable:

1. cost_effective (~$0.003 per page): Fast extraction, lower cost. Best for mostly-text documents.

2. agentic (~$0.01 per page): Balanced quality and cost. Excellent table extraction. (Recommended default).

3. agentic_plus (~$0.03 per page): The highest quality available. Extracts intense detail, perfect alignment, and includes image descriptions.

Summary

• FOR SPEED & SIMPLICITY: Pass {"processor_type": "base"} to the API. It is fast and requires zero configuration.

• FOR PRIVATE, HIGH-QUALITY RAG: Pass {"processor_type": "layout_aware_standard"} to the API. Ensure you have DOCLING_RAY_ENABLED=true set in the environment so the system can use all your CPU cores to process documents faster.

• FOR THE BEST POSSIBLE ACCURACY: Pass {"processor_type": "layout_aware_advanced", "llamaparse_preset": "agentic"} to the API. You must provide your LLAMA_CLOUD_API_KEY in the environment. This is highly recommended if your documents consist heavily of complex financial tables or multi-column research papers.