Kreuzberg

Kreuzberg Document Extraction

Kreuzberg is a high-performance document intelligence library with a Rust core and native bindings for Python, Node.js/TypeScript, Ruby, Go, Java, C#, PHP, and Elixir. It extracts text, tables, metadata, and images from 91+ file formats including PDF, Office documents, images (with OCR), HTML, email, archives, and academic formats.

Use this skill when writing code that:

• Extracts text or metadata from documents
• Performs OCR on scanned documents or images
• Batch-processes multiple files
• Configures extraction options (output format, chunking, OCR, language detection)
• Implements custom plugins (post-processors, validators, OCR backends)

Installation

Python

pip install kreuzberg
# Optional OCR backends:
pip install kreuzberg[easyocr]    # EasyOCR

Node.js

npm install @kreuzberg/node

Rust

# Cargo.toml
[dependencies]
kreuzberg = { version = "4", features = ["tokio-runtime"] }
# features: tokio-runtime (required for sync + batch), pdf, ocr, chunking,
#           embeddings, language-detection, keywords-yake, keywords-rake

CLI

# Download from GitHub releases, or:
cargo install kreuzberg-cli

Quick Start

Python (Async)

from kreuzberg import extract_file

result = await extract_file("document.pdf")
print(result.content)       # extracted text
print(result.metadata)      # document metadata
print(result.tables)        # extracted tables

Python (Sync)

from kreuzberg import extract_file_sync

result = extract_file_sync("document.pdf")
print(result.content)

Node.js

import { extractFile } from "@kreuzberg/node";

const result = await extractFile("document.pdf");
console.log(result.content);
console.log(result.metadata);
console.log(result.tables);

Node.js (Sync)

import { extractFileSync } from "@kreuzberg/node";

const result = extractFileSync("document.pdf");

Rust (Async)

use kreuzberg::{extract_file, ExtractionConfig};

#[tokio::main]
async fn main() -> kreuzberg::Result<()> {
    let config = ExtractionConfig::default();
    let result = extract_file("document.pdf", None, &config).await?;
    println!("{}", result.content);
    Ok(())
}

Rust (Sync) — requires tokio-runtime feature

use kreuzberg::{extract_file_sync, ExtractionConfig};

fn main() -> kreuzberg::Result<()> {
    let config = ExtractionConfig::default();
    let result = extract_file_sync("document.pdf", None, &config)?;
    println!("{}", result.content);
    Ok(())
}

CLI

kreuzberg extract document.pdf
kreuzberg extract document.pdf --format json
kreuzberg extract document.pdf --output-format markdown

Configuration

All languages use the same configuration structure with language-appropriate naming conventions.

Python (snake_case)

from kreuzberg import (
    ExtractionConfig, OcrConfig, TesseractConfig,
    PdfConfig, ChunkingConfig,
)

config = ExtractionConfig(
    ocr=OcrConfig(
        backend="tesseract",
        language="eng",
        tesseract_config=TesseractConfig(psm=6, enable_table_detection=True),
    ),
    pdf_options=PdfConfig(passwords=["secret123"]),
    chunking=ChunkingConfig(max_chars=1000, max_overlap=200),
    output_format="markdown",
)

result = await extract_file("document.pdf", config=config)

Node.js (camelCase)

import { extractFile, type ExtractionConfig } from "@kreuzberg/node";

const config: ExtractionConfig = {
  ocr: { backend: "tesseract", language: "eng" },
  pdfOptions: { passwords: ["secret123"] },
  chunking: { maxChars: 1000, maxOverlap: 200 },
  outputFormat: "markdown",
};

const result = await extractFile("document.pdf", null, config);

Rust (snake_case)

use kreuzberg::{ExtractionConfig, OcrConfig, ChunkingConfig, OutputFormat};

let config = ExtractionConfig {
    ocr: Some(OcrConfig {
        backend: "tesseract".into(),
        language: "eng".into(),
        ..Default::default()
    }),
    chunking: Some(ChunkingConfig {
        max_characters: 1000,
        overlap: 200,
        ..Default::default()
    }),
    output_format: OutputFormat::Markdown,
    ..Default::default()
};

let result = extract_file("document.pdf", None, &config).await?;

Config File (TOML)

output_format = "markdown"

[ocr]
backend = "tesseract"
language = "eng"

[chunking]
max_chars = 1000
max_overlap = 200

[pdf_options]
passwords = ["secret123"]

# CLI: auto-discovers kreuzberg.toml in current/parent directories
kreuzberg extract doc.pdf
# or explicit:
kreuzberg extract doc.pdf --config kreuzberg.toml
kreuzberg extract doc.pdf --config-json '{"ocr":{"backend":"tesseract","language":"deu"}}'

Batch Processing

Python

from kreuzberg import batch_extract_files, batch_extract_files_sync

# Async
results = await batch_extract_files(["doc1.pdf", "doc2.docx", "doc3.xlsx"])

# Sync
results = batch_extract_files_sync(["doc1.pdf", "doc2.docx"])

for result in results:
    print(f"{len(result.content)} chars extracted")

Node.js

import { batchExtractFiles } from "@kreuzberg/node";

const results = await batchExtractFiles(["doc1.pdf", "doc2.docx"]);

Rust — requires tokio-runtime feature

use kreuzberg::{batch_extract_file, ExtractionConfig};

let config = ExtractionConfig::default();
let paths = vec!["doc1.pdf", "doc2.docx"];
let results = batch_extract_file(paths, &config).await?;

CLI

kreuzberg batch *.pdf --format json
kreuzberg batch docs/*.docx --output-format markdown

OCR

OCR runs automatically for images and scanned PDFs. Tesseract is the default backend (native binding, no external install required).

Backends

• Tesseract (default): Built-in native binding. All Tesseract languages supported.
• EasyOCR (Python only): pip install kreuzberg[easyocr]. Pass easyocr_kwargs={"gpu": True}.
• PaddleOCR (Python only): Bundled since 4.8.5, no extra install needed. Pass paddleocr_kwargs={"use_angle_cls": True}.
• Guten (Node.js only): Built-in OCR backend via GutenOcrBackend.

Language Codes

config = ExtractionConfig(ocr=OcrConfig(language="eng"))       # English
config = ExtractionConfig(ocr=OcrConfig(language="eng+deu"))   # Multiple
config = ExtractionConfig(ocr=OcrConfig(language="all"))       # All installed

Force OCR

config = ExtractionConfig(force_ocr=True)  # OCR even if text is extractable

ExtractionResult Fields

Error Handling

Python

from kreuzberg import (
    extract_file_sync, KreuzbergError, ParsingError,
    OCRError, ValidationError, MissingDependencyError,
)

try:
    result = extract_file_sync("file.pdf")
except ParsingError as e:
    print(f"Failed to parse: {e}")
except OCRError as e:
    print(f"OCR failed: {e}")
except ValidationError as e:
    print(f"Invalid input: {e}")
except MissingDependencyError as e:
    print(f"Missing dependency: {e}")
except KreuzbergError as e:
    print(f"Extraction failed: {e}")

Node.js

import {
  extractFile,
  KreuzbergError,
  ParsingError,
  OcrError,
  ValidationError,
  MissingDependencyError,
} from "@kreuzberg/node";

try {
  const result = await extractFile("file.pdf");
} catch (e) {
  if (e instanceof ParsingError) {
    /* ... */
  } else if (e instanceof OcrError) {
    /* ... */
  } else if (e instanceof ValidationError) {
    /* ... */
  } else if (e instanceof KreuzbergError) {
    /* ... */
  }
}

Rust

use kreuzberg::{extract_file, ExtractionConfig, KreuzbergError};

let config = ExtractionConfig::default();
match extract_file("file.pdf", None, &config).await {
    Ok(result) => println!("{}", result.content),
    Err(KreuzbergError::Parsing(msg)) => eprintln!("Parse error: {msg}"),
    Err(KreuzbergError::Ocr(msg)) => eprintln!("OCR error: {msg}"),
    Err(e) => eprintln!("Error: {e}"),
}

Common Pitfalls

1. Python ChunkingConfig fields: Use max_chars and max_overlap, NOT max_characters or overlap. 2. Rust extract_file signature: Third argument is &ExtractionConfig (a reference), not Option. Use &ExtractionConfig::default() for defaults. 3. Rust feature gates: extract_file_sync, batch_extract_file, and batch_extract_file_sync all require features = ["tokio-runtime"] in Cargo.toml. 4. Rust async context: extract_file is async. Use #[tokio::main] or call from an async context. 5. CLI --format vs --output-format: --format controls CLI output (text/json). --output-format controls content format (plain/markdown/djot/html). 6. Node.js extractFile signature: extractFile(path, mimeType?, config?) — mimeType is the second arg (pass null to skip). 7. Python detect_mime_type: The function for detecting from bytes is detect_mime_type(data). For paths use detect_mime_type_from_path(path). 8. Config file field names: Use snake_case in TOML/YAML/JSON config files (e.g., max_chars, max_overlap, pdf_options).

Supported Formats (Summary)

See references/supported-formats.md for the complete format reference with MIME types.

Additional Resources

Detailed reference files for specific topics:

• [Python API Reference](references/python-api.md) — All functions, config classes, plugin protocols, exact signatures
• [Node.js API Reference](references/nodejs-api.md) — All functions, TypeScript interfaces, worker pool APIs
• [Rust API Reference](references/rust-api.md) — All functions with feature gates, structs, Cargo.toml examples
• [CLI Reference](references/cli-reference.md) — All commands, flags, config precedence, exit codes
• [Configuration Reference](references/configuration.md) — TOML/YAML/JSON formats, auto-discovery, env vars, full schema
• [Supported Formats](references/supported-formats.md) — All 85+ formats with file extensions and MIME types
• [Advanced Features](references/advanced-features.md) — Plugins, embeddings, MCP server, API server, security limits
• [Other Language Bindings](references/other-bindings.md) — Go, Ruby, Java, C#, PHP, Elixir, WASM, Docker

Full documentation: <https://docs.kreuzberg.dev> GitHub: <https://github.com/kreuzberg-dev/kreuzberg>

Advanced Features Reference

Kreuzberg provides powerful advanced features for customization, semantic processing, and integration with external systems.

Plugin System

The plugin system allows you to extend Kreuzberg's extraction pipeline with custom post-processors, validators, and OCR backends. Plugins run within the extraction pipeline and have direct access to extraction results.

Custom Post-Processors

Post-processors enrich extraction results after document parsing. They run non-destructively—if a post-processor fails, the extraction succeeds anyway (errors are logged).

=== "Python"

    from kreuzberg import register_post_processor, ExtractionResult

    class MetadataEnricher:
        def name(self) -> str:
            return "metadata_enricher"

        def process(self, result: ExtractionResult) -> ExtractionResult:
            result.metadata["processed_by"] = "metadata_enricher"
            result.metadata["char_count"] = len(result.content)
            return result

        def processing_stage(self) -> str:
            # "early", "middle", or "late"
            return "middle"

        def initialize(self) -> None:
            print("Initializing metadata enricher")

        def shutdown(self) -> None:
            print("Shutting down metadata enricher")

    register_post_processor(MetadataEnricher())

    # Now use extraction with the registered processor
    from kreuzberg import extract_file_sync
    result = extract_file_sync("document.pdf")
    print(result.metadata["char_count"])

=== "TypeScript"

    import { registerPostProcessor, ExtractionResult } from '@kreuzberg/node';

    const enricher = {
        name(): string {
            return "metadata_enricher";
        },

        async process(result: ExtractionResult): Promise<ExtractionResult> {
            result.metadata.processed_by = "metadata_enricher";
            result.metadata.char_count = result.content.length;
            return result;
        },

        processingStage?(): "early" | "middle" | "late" {
            return "middle";
        },

        async initialize?(): Promise<void> {
            console.log("Initializing metadata enricher");
        },

        async shutdown?(): Promise<void> {
            console.log("Shutting down metadata enricher");
        }
    };

    registerPostProcessor(enricher);

    // Now use extraction with the registered processor
    const result = await extractFile("document.pdf");
    console.log(result.metadata.char_count);

Custom Validators

Validators perform quality checks on extraction results. Unlike post-processors, validator failures cause the entire extraction to fail. Use validators to enforce quality standards.

=== "Python"

    from kreuzberg import register_validator, ExtractionResult, ValidationError

    class MinimumContentValidator:
        def name(self) -> str:
            return "min_content_validator"

        def validate(self, result: ExtractionResult) -> None:
            if len(result.content) < 100:
                raise ValidationError("Extracted content too short (< 100 chars)")

        def priority(self) -> int:
            # Higher priority runs first (0-1000, default 50)
            return 100

        def should_validate(self, result: ExtractionResult) -> bool:
            # Only validate PDFs
            return "pdf" in result.mime_type.lower()

        def initialize(self) -> None:
            pass

        def shutdown(self) -> None:
            pass

    register_validator(MinimumContentValidator())

    # Extraction will fail if content < 100 chars
    result = extract_file_sync("document.pdf")

=== "TypeScript"

    import { registerValidator, ExtractionResult } from '@kreuzberg/node';

    const validator = {
        name(): string {
            return "min_content_validator";
        },

        async validate(result: ExtractionResult): Promise<void> {
            if (result.content.length < 100) {
                throw new Error("Extracted content too short (< 100 chars)");
            }
        },

        priority?(): number {
            return 100;
        },

        shouldValidate?(result: ExtractionResult): boolean {
            return result.mimeType.toLowerCase().includes("pdf");
        },

        async initialize?(): Promise<void> {},

        async shutdown?(): Promise<void> {}
    };

    registerValidator(validator);

    // Extraction will fail if content < 100 chars
    const result = await extractFile("document.pdf");

Custom OCR Backends

Implement custom OCR engines by registering an OCR backend. This allows integration with proprietary or specialized OCR solutions.

=== "Python"

    from kreuzberg import register_ocr_backend

    class CustomOcrBackend:
        def name(self) -> str:
            return "custom_ocr"

        def supported_languages(self) -> list[str]:
            return ["eng", "deu", "fra", "spa"]

        def process_image(self, image_bytes: bytes, language: str) -> dict:
            # image_bytes: raw image data
            # language: ISO 639-3 code (e.g., "eng", "deu")

            # Call your OCR engine here
            # text = my_ocr_engine.recognize(image_bytes, language)

            return {
                "content": "Extracted text from image",
                "metadata": {"confidence": 0.95, "language": language},
                "tables": []
            }

        def process_file(self, path: str, language: str) -> dict:
            # Optional: custom file processing
            # Called when extracting OCR from a file path
            with open(path, "rb") as f:
                image_bytes = f.read()
            return self.process_image(image_bytes, language)

        def initialize(self) -> None:
            # Load models, initialize engine
            pass

        def shutdown(self) -> None:
            # Clean up resources
            pass

        def version(self) -> str:
            return "1.0.0"

    register_ocr_backend(CustomOcrBackend())

    # Use in extraction config
    from kreuzberg import ExtractionConfig, OcrConfig, extract_file_sync

    config = ExtractionConfig(
        ocr=OcrConfig(backend="custom_ocr", language="eng")
    )
    result = extract_file_sync("scanned.pdf", config=config)

=== "TypeScript"

    import { registerOcrBackend, ExtractionConfig, extractFile } from '@kreuzberg/node';

    const backend = {
        name(): string {
            return "custom_ocr";
        },

        supportedLanguages(): string[] {
            return ["eng", "deu", "fra", "spa"];
        },

        async processImage(
            imageBytes: Uint8Array | string,
            language: string
        ): Promise<{
            content: string;
            mime_type: string;
            metadata: Record<string, unknown>;
            tables: unknown[];
        }> {
            const buffer = typeof imageBytes === "string"
                ? Buffer.from(imageBytes, "base64")
                : Buffer.from(imageBytes);

            // Call your OCR engine
            // const text = await myOcrEngine.recognize(buffer, language);

            return {
                content: "Extracted text from image",
                mime_type: "text/plain",
                metadata: { confidence: 0.95, language },
                tables: []
            };
        },

        async initialize?(): Promise<void> {
            // Load models, initialize engine
        },

        async shutdown?(): Promise<void> {
            // Clean up resources
        }
    };

    registerOcrBackend(backend);

    // Use in extraction config
    const config: ExtractionConfig = {
        ocr: { backend: "custom_ocr", language: "eng" }
    };
    const result = await extractFile("scanned.pdf", null, config);

Per-File Configuration in Batch Operations

Use FileExtractionConfig to override extraction settings for individual files within a batch. This is useful for mixed-format batches where different documents need different OCR, output, or processing settings.

=== "Python"

    from kreuzberg import (
        batch_extract_files_sync,
        ExtractionConfig, FileExtractionConfig, OcrConfig,
    )

    config = ExtractionConfig(output_format="markdown")
    paths = ["report.pdf", "scan.tiff"]
    file_configs = [
        None,  # use batch defaults
        FileExtractionConfig(
            force_ocr=True,
            ocr=OcrConfig(backend="tesseract", language="deu"),
        ),
    ]
    results = batch_extract_files_sync(paths, config, file_configs=file_configs)

=== "TypeScript"

    import { batchExtractFilesSync } from '@kreuzberg/node';

    const results = batchExtractFilesSync(
      ['report.pdf', 'scan.tiff'],
      { outputFormat: 'markdown' },
      [null, { forceOcr: true, ocr: { backend: 'tesseract', language: 'deu' } }],
    );

All ExtractionConfig fields except batch-level concerns (max_concurrent_extractions, use_cache, acceleration, security_limits) can be overridden. None/null fields inherit from the batch default.

Embeddings

Generate vector embeddings for text chunks using ONNX-based models. Embeddings enable semantic search, clustering, and similarity operations on extracted content.

Requirements: ONNX Runtime 1.22.x or later

=== "Python"

    from kreuzberg import (
        ExtractionConfig, ChunkingConfig, EmbeddingConfig,
        EmbeddingModelType, list_embedding_presets,
        get_embedding_preset, extract_file_sync
    )

    # List available embedding presets
    presets = list_embedding_presets()
    print(f"Available presets: {presets}")  # ['balanced', 'compact', 'large']

    # Get details about a preset
    preset_info = get_embedding_preset("balanced")
    print(f"Model: {preset_info.model_name}")
    print(f"Dimensions: {preset_info.dimensions}")
    print(f"Recommended chunk size: {preset_info.chunk_size}")

    # Method 1: Use preset (recommended)
    config = ExtractionConfig(
        chunking=ChunkingConfig(
            max_chars=512,
            max_overlap=100,
            embedding=EmbeddingConfig(
                model=EmbeddingModelType.preset("balanced"),
                normalize=True,
                batch_size=32
            )
        )
    )

    # Method 2: Use specific fastembed model
    config = ExtractionConfig(
        chunking=ChunkingConfig(
            embedding=EmbeddingConfig(
                model=EmbeddingModelType.fastembed(
                    model="BAAI/bge-small-en-v1.5",
                    dimensions=384
                ),
                normalize=True
            )
        )
    )

    # Method 3: Use custom ONNX model from HuggingFace
    config = ExtractionConfig(
        chunking=ChunkingConfig(
            embedding=EmbeddingConfig(
                model=EmbeddingModelType.custom(
                    model_id="sentence-transformers/all-MiniLM-L6-v2",
                    dimensions=384
                ),
                cache_dir="/path/to/model/cache"
            )
        )
    )

    result = extract_file_sync("document.pdf", config=config)

    # Access embeddings in chunks
    for chunk in result.chunks:
        embedding = chunk.embedding  # list[float] or None
        print(f"Chunk: {chunk.content[:50]}...")
        print(f"Embedding dimensions: {len(embedding) if embedding else 0}")

=== "TypeScript"

    import {
        ExtractionConfig, ChunkingConfig,
        listEmbeddingPresets, getEmbeddingPreset,
        extractFile
    } from '@kreuzberg/node';

    // List available embedding presets
    const presets = listEmbeddingPresets();
    console.log(`Available presets: ${presets}`);  // ['balanced', 'compact', 'large']

    // Get details about a preset
    const preset = getEmbeddingPreset("balanced");
    console.log(`Model: ${preset.modelName}`);
    console.log(`Dimensions: ${preset.dimensions}`);
    console.log(`Recommended chunk size: ${preset.chunkSize}`);

    // Method 1: Use preset (recommended)
    const config: ExtractionConfig = {
        chunking: {
            maxChars: 512,
            maxOverlap: 100,
            embedding: {
                model: { type: 'preset', name: 'balanced' },
                normalize: true,
                batchSize: 32
            }
        }
    };

    // Method 2: Use specific fastembed model
    const config2: ExtractionConfig = {
        chunking: {
            embedding: {
                model: {
                    type: 'fastembed',
                    model: 'BAAI/bge-small-en-v1.5',
                    dimensions: 384
                },
                normalize: true
            }
        }
    };

    // Method 3: Use custom ONNX model
    const config3: ExtractionConfig = {
        chunking: {
            embedding: {
                model: {
                    type: 'custom',
                    modelId: 'sentence-transformers/all-MiniLM-L6-v2',
                    dimensions: 384
                },
                cacheDir: '/path/to/model/cache'
            }
        }
    };

    const result = await extractFile("document.pdf", null, config);

    // Access embeddings in chunks
    if (result.chunks) {
        for (const chunk of result.chunks) {
            const embedding = chunk.embedding;  // number[] | null
            console.log(`Chunk: ${chunk.content.substring(0, 50)}...`);
            console.log(`Embedding dimensions: ${embedding?.length ?? 0}`);
        }
    }

Keyword Extraction

Extract important keywords and phrases from documents using YAKE (Yet Another Keyword Extractor) or RAKE (Rapid Automatic Keyword Extraction) algorithms.

=== "Python"

    from kreuzberg import (
        ExtractionConfig, KeywordConfig, KeywordAlgorithm,
        YakeParams, RakeParams, extract_file_sync
    )

    # YAKE algorithm (unsupervised, good for general use)
    config = ExtractionConfig(
        keywords=KeywordConfig(
            algorithm=KeywordAlgorithm.Yake,
            max_keywords=15,
            min_score=0.1,
            ngram_range=(1, 3),
            language="en",
            yake_params=YakeParams(window_size=2)
        )
    )

    # RAKE algorithm (co-occurrence based)
    config = ExtractionConfig(
        keywords=KeywordConfig(
            algorithm=KeywordAlgorithm.Rake,
            max_keywords=10,
            min_score=0.0,
            language="en",
            rake_params=RakeParams(
                min_word_length=3,
                max_words_per_phrase=3
            )
        )
    )

    result = extract_file_sync("document.pdf", config=config)

    # Access extracted keywords
    if result.keywords:
        for keyword in result.keywords:
            print(f"Text: {keyword.text}")
            print(f"Score: {keyword.score}")
            print(f"Algorithm: {keyword.algorithm}")

=== "TypeScript"

    import {
        ExtractionConfig, KeywordConfig,
        extractFile
    } from '@kreuzberg/node';

    // YAKE algorithm
    const config: ExtractionConfig = {
        keywords: {
            algorithm: "yake",
            maxKeywords: 15,
            minScore: 0.1,
            ngramRange: [1, 3],
            language: "en",
            yakeParams: {
                windowSize: 2
            }
        }
    };

    // RAKE algorithm
    const config2: ExtractionConfig = {
        keywords: {
            algorithm: "rake",
            maxKeywords: 10,
            minScore: 0.0,
            language: "en",
            rakeParams: {
                minWordLength: 3,
                maxWordsPerPhrase: 3
            }
        }
    };

    const result = await extractFile("document.pdf", null, config);

    // Access extracted keywords
    if (result.keywords) {
        for (const keyword of result.keywords) {
            console.log(`Text: ${keyword.text}`);
            console.log(`Score: ${keyword.score}`);
            console.log(`Algorithm: ${keyword.algorithm}`);
        }
    }

Language Detection

Automatically detect the language(s) in documents using ISO 639-1 language codes.

=== "Python"

    from kreuzberg import (
        ExtractionConfig, LanguageDetectionConfig,
        extract_file_sync
    )

    # Enable language detection
    config = ExtractionConfig(
        language_detection=LanguageDetectionConfig(
            enabled=True,
            min_confidence=0.8,
            detect_multiple=False
        )
    )

    result = extract_file_sync("multilingual.pdf", config=config)

    # Access detected languages
    if result.detected_languages:
        for lang_code in result.detected_languages:
            print(f"Detected language: {lang_code}")  # e.g., "en", "de", "fr"

=== "TypeScript"

    import {
        ExtractionConfig, LanguageDetectionConfig,
        extractFile
    } from '@kreuzberg/node';

    const config: ExtractionConfig = {
        languageDetection: {
            enabled: true,
            minConfidence: 0.8,
            detectMultiple: false
        }
    };

    const result = await extractFile("multilingual.pdf", null, config);

    // Access detected languages
    if (result.detectedLanguages) {
        for (const langCode of result.detectedLanguages) {
            console.log(`Detected language: ${langCode}`);  // e.g., "en", "de", "fr"
        }
    }

Token Reduction

Reduce the number of tokens in extracted content for cost optimization when working with LLM APIs. Higher modes are more aggressive but may lose more information.

=== "Python"

    from kreuzberg import (
        ExtractionConfig, TokenReductionConfig,
        extract_file_sync
    )

    # Light token reduction
    config = ExtractionConfig(
        token_reduction=TokenReductionConfig(
            mode="light",
            preserve_important_words=True
        )
    )

    # Moderate reduction
    config = ExtractionConfig(
        token_reduction=TokenReductionConfig(
            mode="moderate",
            preserve_important_words=True
        )
    )

    # Aggressive reduction
    config = ExtractionConfig(
        token_reduction=TokenReductionConfig(
            mode="aggressive",
            preserve_important_words=True
        )
    )

    # Maximum reduction
    config = ExtractionConfig(
        token_reduction=TokenReductionConfig(
            mode="maximum",
            preserve_important_words=True
        )
    )

    result = extract_file_sync("document.pdf", config=config)
    print(f"Reduced content length: {len(result.content)}")

=== "TypeScript"

    import {
        ExtractionConfig, TokenReductionConfig,
        extractFile
    } from '@kreuzberg/node';

    const config: ExtractionConfig = {
        tokenReduction: {
            mode: "moderate",
            preserveImportantWords: true
        }
    };

    const result = await extractFile("document.pdf", null, config);
    console.log(`Reduced content length: ${result.content.length}`);

Token Reduction Modes:

• off: No reduction (default)
• light: Remove extra whitespace and redundant punctuation
• moderate: Also remove common filler words and some formatting
• aggressive: Also remove longer stopwords and collapse similar phrases
• maximum: Maximum reduction while preserving semantic content

Page Extraction

Extract and track per-page content separately. Useful for multi-page documents where you need page-level granularity.

=== "Python"

    from kreuzberg import (
        ExtractionConfig, PageConfig,
        extract_file_sync
    )

    config = ExtractionConfig(
        pages=PageConfig(
            extract_pages=True,
            insert_page_markers=True,
            marker_format="\n\n<!-- PAGE {page_num} -->\n\n"
        )
    )

    result = extract_file_sync("multi_page.pdf", config=config)

    # Access per-page content
    if result.pages:
        for page in result.pages:
            print(f"Page {page.page_number}:")
            print(f"Content: {page.content[:100]}...")
            print(f"Tables: {len(page.tables)}")
            print(f"Images: {len(page.images)}")

=== "TypeScript"

    import {
        ExtractionConfig, PageExtractionConfig,
        extractFile
    } from '@kreuzberg/node';

    const config: ExtractionConfig = {
        pages: {
            extractPages: true,
            insertPageMarkers: true,
            markerFormat: "\n\n<!-- PAGE {page_num} -->\n\n"
        }
    };

    const result = await extractFile("multi_page.pdf", null, config);

    // Access per-page content
    if (result.pages) {
        for (const page of result.pages) {
            console.log(`Page ${page.pageNumber}:`);
            console.log(`Content: ${page.content.substring(0, 100)}...`);
            console.log(`Tables: ${page.tables.length}`);
            console.log(`Images: ${page.images.length}`);
        }
    }

Element-Based Output

Extract semantic elements instead of unified content. This format is compatible with the Unstructured library and provides structured access to different content types (titles, headings, text, tables, images, etc.).

=== "Python"

    from kreuzberg import ExtractionConfig, ResultFormat, extract_file_sync

    config = ExtractionConfig(
        result_format="element_based"
    )

    result = extract_file_sync("document.pdf", config=config)

    # Access semantic elements
    if result.elements:
        for element in result.elements:
            print(f"Type: {element.element_type}")  # title, heading, narrative_text, etc.
            print(f"Text: {element.text}")
            if element.metadata.get("page_number"):
                print(f"Page: {element.metadata['page_number']}")

=== "TypeScript"

    import { ExtractionConfig, extractFile } from '@kreuzberg/node';

    const config: ExtractionConfig = {
        resultFormat: "element_based"
    };

    const result = await extractFile("document.pdf", null, config);

    // Access semantic elements
    if (result.elements) {
        for (const element of result.elements) {
            console.log(`Type: ${element.elementType}`);
            console.log(`Text: ${element.text}`);
            if (element.metadata.pageNumber) {
                console.log(`Page: ${element.metadata.pageNumber}`);
            }
        }
    }

Element Types:

• title: Document or section title
• heading: Section headings
• narrative_text: Regular paragraph text
• list_item: Items in bullet/numbered lists
• table: Table structures
• image: Images or figures
• page_break: Page boundaries
• code_block: Code snippets
• block_quote: Quoted text
• footer: Footer content
• header: Header content

Djot Content

Output extracted content in Djot markup format (a lighter alternative to Markdown with enhanced structure).

=== "Python"

    from kreuzberg import ExtractionConfig, OutputFormat, extract_file_sync

    config = ExtractionConfig(
        output_format="djot"
    )

    result = extract_file_sync("document.pdf", config=config)
    print(result.content)  # Djot-formatted content

    # Access structured Djot content
    if result.djot_content:
        print(f"Plain text: {result.djot_content['plain_text']}")
        print(f"Blocks: {result.djot_content['blocks']}")
        print(f"Links: {result.djot_content['links']}")
        print(f"Images: {result.djot_content['images']}")
        print(f"Footnotes: {result.djot_content['footnotes']}")

=== "TypeScript"

    import { ExtractionConfig, extractFile } from '@kreuzberg/node';

    const config: ExtractionConfig = {
        outputFormat: "djot"
    };

    const result = await extractFile("document.pdf", null, config);
    console.log(result.content);  // Djot-formatted content

    // Access structured Djot content (if available)
    if (result.djotContent) {
        console.log(`Plain text: ${result.djotContent.plain_text}`);
        console.log(`Blocks: ${result.djotContent.blocks}`);
        console.log(`Links: ${result.djotContent.links}`);
        console.log(`Images: ${result.djotContent.images}`);
        console.log(`Footnotes: ${result.djotContent.footnotes}`);
    }

API Server

Run Kreuzberg as an HTTP API server for integration with external services.

# Start server on default port 8000
kreuzberg serve

# Custom host and port
kreuzberg serve --host 0.0.0.0 --port 9000

# Enable CORS and other options
kreuzberg serve --host localhost --port 8000

API Endpoints:

• POST /extract - Extract from uploaded file
• POST /batch - Batch extraction
• POST /detect - Detect MIME type

Example:

curl -X POST -F "file=@document.pdf" http://localhost:8000/extract

MCP Server

Run Kreuzberg as a Model Context Protocol server for integration with Claude and other AI models.

# Start MCP server with stdio transport
kreuzberg mcp --transport stdio

# Start MCP server with HTTP transport
kreuzberg mcp --transport http --host 127.0.0.1 --port 8001

The MCP server exposes extraction functions to AI models, allowing them to process documents directly.

Security Limits

Set resource limits to prevent abuse and control memory/file size consumption.

=== "Python"

    from kreuzberg import ExtractionConfig, extract_file_sync

    config = ExtractionConfig(
        security_limits={
            "max_file_size": 100_000_000,      # 100 MB
            "max_archive_files": 1000,
            "max_text_length": 10_000_000,     # 10 MB of text
            "max_pages": 10000,
            "max_concurrent_extractions": 4
        }
    )

    result = extract_file_sync("document.pdf", config=config)

=== "TypeScript"

    import { ExtractionConfig, extractFile } from '@kreuzberg/node';

    const config: ExtractionConfig = {
        securityLimits: {
            max_file_size: 100_000_000,        // 100 MB
            max_archive_files: 1000,
            max_text_length: 10_000_000,       // 10 MB of text
            max_pages: 10000,
            max_concurrent_extractions: 4
        }
    };

    const result = await extractFile("document.pdf", null, config);

Common Limits:

• max_file_size: Maximum input file size in bytes
• max_archive_files: Maximum files in archives (zip, tar, etc.)
• max_text_length: Maximum extracted text length
• max_pages: Maximum number of pages to process
• max_concurrent_extractions: Maximum concurrent extraction operations

Caching

Extraction results are cached by default to improve performance on repeated extractions of identical documents. Control caching behavior through configuration.

=== "Python"

    from kreuzberg import ExtractionConfig, extract_file_sync

    # Enable caching (default)
    config = ExtractionConfig(use_cache=True)
    result = extract_file_sync("document.pdf", config=config)

    # Disable caching for a specific extraction
    config = ExtractionConfig(use_cache=False)
    result = extract_file_sync("document.pdf", config=config)

=== "TypeScript"

    import { ExtractionConfig, extractFile } from '@kreuzberg/node';

    // Enable caching (default)
    const config: ExtractionConfig = { useCache: true };
    const result = await extractFile("document.pdf", null, config);

    // Disable caching
    const config2: ExtractionConfig = { useCache: false };
    const result2 = await extractFile("document.pdf", null, config2);

CLI Cache Management:

# View cache statistics
kreuzberg cache stats

# Clear all cached results
kreuzberg cache clear

Caching is transparent and automatic—same input produces cached output instantly on subsequent extractions.

Kreuzberg CLI Reference

Comprehensive command-line interface for the Kreuzberg document intelligence library.

Installation

Install from crates.io:

cargo install kreuzberg-cli

Or download pre-built binaries from GitHub Releases.

Commands

extract

Extract text and structure from a single document.

kreuzberg extract <path> [FLAGS]

Positional Arguments

• <path> — Path to the document file

Flags

• -c, --config <path> — Path to config file (TOML, YAML, or JSON). Auto-discovers kreuzberg.{toml,yaml,json} in current and parent directories if omitted.
• --config-json <json> — Inline JSON configuration (merged after config file, before CLI flags).
• --config-json-base64 <base64> — Base64-encoded JSON configuration.
• -m, --mime-type <type> — MIME type hint (auto-detected if not provided).
• -f, --format <text|json> — CLI output format (default: text). Controls how results display, not extraction content format.
• --content-format <plain|markdown|djot|html> — Extraction content format (default: plain). Controls format of extracted content. (Note: --output-format is a deprecated alias.)
• --ocr <bool> — Enable OCR processing.
• --ocr-backend <BACKEND> — OCR backend: tesseract, paddle-ocr, easyocr.
• --ocr-language <LANG> — OCR language code.
• --ocr-auto-rotate <bool> — Auto-rotate images before OCR.
• --force-ocr <bool> — Force OCR even if text extraction succeeds.
• --disable-ocr <bool> — Disable OCR entirely (even for images).
• --no-cache <bool> — Disable caching.
• --chunk <bool> — Enable text chunking.
• --chunk-size <n> — Chunk size in characters.
• --chunk-overlap <n> — Chunk overlap in characters.
• --chunking-tokenizer <model> — Tokenizer model for token-based sizing.
• --include-structure <bool> — Include hierarchical document structure.
• --quality <bool> — Enable quality processing.
• --detect-language <bool> — Enable language detection.
• --layout — Enable layout detection (RT-DETR v2). Use --layout false to disable.
• --layout-confidence <float> — Layout confidence threshold (0.0-1.0).
• --layout-table-model <model> — Table structure model: tatr, slanet_wired, slanet_wireless, slanet_plus, slanet_auto, disabled.
• --acceleration <provider> — ONNX execution provider: auto, cpu, coreml, cuda, tensorrt.
• --extract-pages <bool> — Extract pages as separate array.
• --page-markers <bool> — Insert page marker comments.
• --extract-images <bool> — Enable image extraction.
• --target-dpi <n> — Target DPI for images (36-2400).
• --pdf-password <pass> — Password for encrypted PDFs (repeatable).
• --pdf-extract-images <bool> — Extract images from PDF pages.
• --pdf-extract-metadata <bool> — Extract PDF metadata.
• --token-reduction <level> — Token reduction: off, light, moderate, aggressive, maximum.
• --msg-codepage <n> — Windows codepage fallback for MSG files.
• --max-concurrent <n> — Max parallel extractions in batch mode.
• --max-threads <n> — Cap all internal thread pools.
• --cache-namespace <name> — Cache namespace for tenant isolation.
• --cache-ttl-secs <n> — Per-request cache TTL in seconds.

Examples

# Extract with default settings
kreuzberg extract document.pdf

# Extract with OCR enabled
kreuzberg extract scanned.pdf --ocr true

# Extract with specific output format
kreuzberg extract doc.docx --output-format markdown

# Extract with inline JSON config
kreuzberg extract file.pdf --config-json '{"ocr":{"backend":"tesseract"}}'

# Extract with base64-encoded config
kreuzberg extract file.pdf --config-json-base64 eyJvY3IiOnsiYmFja2VuZCI6InRlc3NlcmFjdCJ9fQ==

# Extract and output as JSON
kreuzberg extract doc.pdf --format json

# Extract with chunking
kreuzberg extract large-doc.pdf --chunk true --chunk-size 2000 --chunk-overlap 200

# Layout-aware markdown extraction
kreuzberg extract document.pdf --layout --content-format markdown

# With custom confidence threshold
kreuzberg extract document.pdf --layout-confidence 0.7 --content-format markdown

batch

Batch extract from multiple documents in parallel.

kreuzberg batch <paths...> [FLAGS]

Positional Arguments

• <paths...> — One or more document file paths

Flags

• -c, --config <path> — Path to config file (TOML, YAML, or JSON). Auto-discovers kreuzberg.{toml,yaml,json} in current and parent directories if omitted.
• --config-json <json> — Inline JSON configuration (merged after config file, before CLI flags).
• --config-json-base64 <base64> — Base64-encoded JSON configuration.
• -f, --format <text|json> — CLI output format (default: json). Controls how results display, not extraction content format.
• All extraction override flags from extract are also supported (e.g., --content-format, --ocr, --layout, --force-ocr, --no-cache, --quality, --acceleration, etc.). See the extract command flags for the full list.

Notes

• Batch command defaults to JSON output format (unlike extract which defaults to text).
• Does not support --mime-type or --detect-language flags.

Examples

# Batch extract multiple PDFs
kreuzberg batch document1.pdf document2.pdf document3.pdf

# Batch extract with glob patterns (shell expansion)
kreuzberg batch *.pdf

# Batch extract with custom output format
kreuzberg batch doc1.pdf doc2.pdf --output-format markdown

# Batch extract with OCR
kreuzberg batch scanned*.pdf --ocr true

# Batch extract with text output format
kreuzberg batch files*.docx --format text

detect

Identify MIME type of a file.

kreuzberg detect <path> [FLAGS]

Positional Arguments

• <path> — Path to the file

Flags

• -f, --format <text|json> — Output format (default: text)

Examples

# Detect MIME type (text output)
kreuzberg detect unknown-file.bin

# Detect MIME type (JSON output)
kreuzberg detect file.xyz --format json

version

Display version information.

kreuzberg version [FLAGS]

Flags

• -f, --format <text|json> — Output format (default: text)

Examples

# Show version as text
kreuzberg version

# Show version as JSON
kreuzberg version --format json

cache

Manage extraction cache.

cache stats

Display cache statistics.

kreuzberg cache stats [FLAGS]

Flags

• --cache-dir <path> — Cache directory (default: .kreuzberg in current directory)
• -f, --format <text|json> — Output format (default: text)

Examples

# Show cache stats
kreuzberg cache stats

# Show cache stats as JSON
kreuzberg cache stats --format json

# Show stats for specific cache directory
kreuzberg cache stats --cache-dir /tmp/my-cache

cache clear

Clear all cached extractions.

kreuzberg cache clear [FLAGS]

Flags

• --cache-dir <path> — Cache directory (default: .kreuzberg in current directory)
• -f, --format <text|json> — Output format (default: text)

Examples

# Clear cache
kreuzberg cache clear

# Clear specific cache directory
kreuzberg cache clear --cache-dir /tmp/my-cache

serve

Start the API server (requires api feature).

kreuzberg serve [FLAGS]

Flags

• -H, --host <host> — Host to bind to (e.g., 127.0.0.1 or 0.0.0.0). CLI arg overrides config file and environment variables.
• -p, --port <port> — Port to bind to. CLI arg overrides config file and environment variables.
• -c, --config <path> — Path to config file (TOML, YAML, or JSON). Auto-discovers kreuzberg.{toml,yaml,json} in current and parent directories if omitted.

Configuration Precedence

1. CLI arguments (--host, --port) 2. Environment variables (KREUZBERG_HOST, KREUZBERG_PORT) 3. Config file ([server] section) 4. Built-in defaults (127.0.0.1:8000)

Examples

# Start server with defaults
kreuzberg serve

# Start server on specific host and port
kreuzberg serve --host 0.0.0.0 --port 3000

# Start server with config file
kreuzberg serve --config kreuzberg.toml

# Start server (environment variables override defaults)
KREUZBERG_HOST=192.168.1.100 KREUZBERG_PORT=8080 kreuzberg serve

mcp

Start the Model Context Protocol (MCP) server (requires mcp feature).

kreuzberg mcp [FLAGS]

Flags

• -c, --config <path> — Path to config file (TOML, YAML, or JSON). Auto-discovers kreuzberg.{toml,yaml,json} in current and parent directories if omitted.
• --transport <stdio|http> — Transport mode (default: stdio)
• --host <host> — HTTP host for http transport (default: 127.0.0.1)
• --port <port> — HTTP port for http transport (default: 8001)

Examples

# Start MCP server with stdio transport
kreuzberg mcp

# Start MCP server with HTTP transport
kreuzberg mcp --transport http

# Start MCP server on custom HTTP host/port
kreuzberg mcp --transport http --host 0.0.0.0 --port 9000

# Start MCP server with config file
kreuzberg mcp --config kreuzberg.toml

Configuration

File Format

Configuration files support three formats with automatic detection:

• TOML — .toml extension (recommended)
• YAML — .yaml or .yml extension
• JSON — .json extension

Configuration Precedence

Settings are applied in order from highest to lowest priority:

1. Individual CLI flags (e.g., --ocr true, --output-format markdown) 2. Inline JSON config (--config-json or --config-json-base64) 3. Config file (explicit --config path.toml or auto-discovered) 4. Default values (built-in library defaults)

Auto-Discovery

When no config file is specified, Kreuzberg searches for configuration in this order:

1. kreuzberg.toml in current directory 2. kreuzberg.yaml in current directory 3. kreuzberg.json in current directory 4. Parent directories (same search pattern, up to filesystem root)

Example Configuration

# Top-level extraction options
use_cache = true
enable_quality_processing = true
force_ocr = false
output_format = "markdown"

# OCR settings
[ocr]
backend = "tesseract"
language = "eng"

# Chunking settings
[chunking]
max_chars = 2000
max_overlap = 200

# Language detection
[language_detection]
enabled = true

# Server configuration (for serve command)
[server]
host = "127.0.0.1"
port = 8000

Exit Codes

• 0 — Success
• Non-zero — Error (see stderr for details)

Error Handling

The CLI validates input and provides clear error messages:

• File not found — Verify path exists and is readable
• Invalid MIME type — Ensure file is accessible and format is supported
• Invalid JSON — Check --config-json syntax
• Invalid config file — Verify TOML/YAML/JSON format
• Invalid chunk parameters — Ensure chunk-size > 0 and overlap < chunk-size

Environment Variables

• RUST_LOG — Set logging level (e.g., RUST_LOG=debug)
• KREUZBERG_HOST — Server bind host (used by serve command)
• KREUZBERG_PORT — Server bind port (used by serve command)

Common Patterns

Extract with Custom Configuration

kreuzberg extract document.pdf \
  --content-format markdown \
  --ocr true \
  --quality true

Batch Process with Config File

kreuzberg batch *.pdf --config extraction-config.toml

CI/CD Integration

# Extract to JSON for downstream processing
kreuzberg extract file.pdf --format json | jq '.content'

# Batch process with error handling
kreuzberg batch docs/*.pdf --format json || exit 1

Performance Tuning

# Disable cache for temporary processing
kreuzberg extract file.pdf --no-cache true

# Enable chunking for large documents
kreuzberg extract large-file.pdf \
  --chunk true \
  --chunk-size 5000 \
  --chunk-overlap 500

Debugging

Enable detailed logging:

RUST_LOG=debug kreuzberg extract document.pdf

Check cache statistics:

kreuzberg cache stats --format json

Detect file MIME type:

kreuzberg detect unknown-file --format json

Configuration Reference

Kreuzberg uses a hierarchical configuration system supporting multiple formats and auto-discovery mechanisms. This reference covers all available configuration options, field names across programming languages, and loading strategies.

Supported Formats

Kreuzberg configurations can be defined in three formats:

• TOML (recommended): kreuzberg.toml
• YAML: kreuzberg.yaml
• JSON: kreuzberg.json

All formats support the same schema and configuration options.

Auto-Discovery

When no configuration file is explicitly specified, Kreuzberg searches for configuration files in the following order:

1. Current working directory: kreuzberg.toml, kreuzberg.yaml, kreuzberg.json 2. Parent directories (recursively up the tree, same file name pattern)

The first matching configuration file is loaded.

Programmatic Loading

Python

from kreuzberg import ExtractionConfig

# Load from explicit path
config = ExtractionConfig.from_file("kreuzberg.toml")

# Auto-discover configuration
config = ExtractionConfig.discover()

Node.js / TypeScript

import { ExtractionConfig } from "@kreuzberg/node";

// Load from explicit path
const config = ExtractionConfig.fromFile("kreuzberg.toml");

// Auto-discover configuration
const config = ExtractionConfig.discover();

CLI

# Explicit configuration file
kreuzberg extract --config kreuzberg.toml document.pdf

# Auto-discovery (searches default locations)
kreuzberg extract document.pdf

Configuration Schema

The complete TOML schema with all available sections and options:

Top-Level Options

use_cache = true
enable_quality_processing = true
force_ocr = false
output_format = "markdown"
result_format = "text"
max_concurrent_extractions = 4

OCR Configuration

[ocr]
backend = "tesseract"
language = "eng"

Tesseract Configuration

[ocr.tesseract_config]
psm = 3
oem = 3
min_confidence = 0.0
output_format = "text"
enable_table_detection = false
table_min_confidence = 0.5
table_column_threshold = 50
table_row_threshold_ratio = 0.5
use_cache = true

Tesseract Preprocessing

[ocr.tesseract_config.preprocessing]
target_dpi = 300
auto_rotate = true
deskew = true
denoise = true
contrast_enhance = true
binarization_method = "otsu"
invert_colors = false

PDF Options

[pdf_options]
extract_images = true
extract_metadata = true

[pdf_options.hierarchy]
enabled = true
k_clusters = 6
include_bbox = true
ocr_coverage_threshold = 0.5

Image Processing

[images]
extract_images = true
target_dpi = 300
max_image_dimension = 4096
auto_adjust_dpi = true
min_dpi = 72
max_dpi = 600

Chunking Configuration

[chunking]
max_chars = 1000
max_overlap = 200

[chunking.embedding]
batch_size = 32
normalize = true
show_download_progress = true
cache_dir = "~/.cache/kreuzberg/embeddings"

[chunking.embedding.model]
type = "preset"
name = "balanced"

Keywords Configuration

[keywords]
algorithm = "yake"
max_keywords = 10
min_score = 0.0
ngram_range = [1, 3]
language = "en"

Token Reduction

[token_reduction]
mode = "off"
preserve_important_words = true

Language Detection

[language_detection]
enabled = true
min_confidence = 0.8
detect_multiple = false

Post-Processor

[postprocessor]
enabled = true

FileExtractionConfig (Per-File Overrides)

Passed as an optional parameter to batch_extract_file / batch_extract_bytes (and their sync variants) to override settings per file in a batch. All fields optional — None = use batch default. The separate _with_configs functions were removed in v4.5.0.

Overridable fields: enable_quality_processing, ocr, force_ocr, chunking, images, pdf_options, token_reduction, language_detection, pages, keywords, postprocessor, html_options, result_format, output_format, include_document_structure, layout.

Batch-level only (not overridable): max_concurrent_extractions, use_cache, acceleration, security_limits.

Merge semantics: For each file, FileExtractionConfig fields are overlaid on the batch ExtractionConfig. None falls through to batch default; Some(value) replaces the batch default for that file.

# FileExtractionConfig cannot be specified in config files —
# it is a programmatic API for per-file overrides at runtime.

Naming Conventions

Kreuzberg uses consistent naming conventions across different contexts:

When switching between languages, apply the appropriate conversion:

• Python → Node.js: snake_case to camelCase
• CLI → Python: kebab-case to snake_case
• TOML → Python: No conversion needed (both use snake_case)

Environment Variables

The following environment variables can override configuration:

Configuration Merging

Configuration sources are merged in priority order (highest to lowest):

1. CLI flags (highest priority) 2. Inline JSON configuration (programmatic) 3. Configuration file (lowest priority)

Later sources override earlier ones. For example, a CLI flag --max-chars 2000 overrides max_chars = 1000 in the configuration file.

Example Configurations

Minimal Configuration

use_cache = true
enable_quality_processing = true

[ocr]
backend = "tesseract"
language = "eng"

High-Quality PDF Extraction

use_cache = true
enable_quality_processing = true
force_ocr = false

[ocr]
backend = "tesseract"
language = "eng"

[ocr.tesseract_config]
psm = 3
oem = 3
enable_table_detection = true
table_min_confidence = 0.7

[pdf_options]
extract_images = true
extract_metadata = true

[pdf_options.hierarchy]
enabled = true
k_clusters = 6

[images]
extract_images = true
target_dpi = 300

Semantic Search Configuration

[chunking]
max_chars = 800
max_overlap = 150

[chunking.embedding]
batch_size = 32
normalize = true
cache_dir = "~/.cache/kreuzberg/embeddings"

[chunking.embedding.model]
type = "preset"
name = "accurate"

[keywords]
algorithm = "yake"
max_keywords = 15

Field Name Reference

Critical field names to use in configuration files:

• max_chars (NOT max_characters)
• max_overlap (NOT overlap)
• table_min_confidence
• table_column_threshold
• table_row_threshold_ratio
• ocr_coverage_threshold
• k_clusters
• include_bbox
• enable_table_detection
• auto_rotate
• auto_adjust_dpi
• show_download_progress
• min_confidence
• detect_multiple

Always verify field names against the source configuration file when adding new options.

Node.js/TypeScript API Reference

Overview

Package: @kreuzberg/node — A high-performance TypeScript SDK built on a Rust core for document intelligence and content extraction.

Supports both ESM (import) and CommonJS (require):

// ESM
import { extractFile, batchExtractFiles } from "@kreuzberg/node";

// CommonJS
const { extractFile, batchExtractFiles } = require("@kreuzberg/node");

Current Version: 4.2.14

---

Core Extraction Functions

All extraction functions return ExtractionResult containing extracted content, metadata, tables, and optional chunks/images.

Single File Extraction

extractFile(filePath, mimeType?, config?): Promise<ExtractionResult>

Extract content from a single file asynchronously.

import { extractFile } from "@kreuzberg/node";

// Auto-detect MIME type from file extension
const result = await extractFile("document.pdf");
console.log(result.content);

// Explicit MIME type
const result2 = await extractFile("document.pdf", "application/pdf");

// With configuration
const result3 = await extractFile("document.pdf", null, {
  chunking: {
    maxChars: 1000,
    maxOverlap: 200,
  },
});

Parameters:

• filePath: string — Path to the file to extract
• mimeType?: string | null — Optional MIME type hint (auto-detect if null)
• config?: ExtractionConfig — Optional extraction configuration

Returns: Promise<ExtractionResult>

Throws: ParsingError, OcrError, ValidationError, KreuzbergError

extractFileSync(filePath, mimeType?, config?): ExtractionResult

Extract content from a single file synchronously.

import { extractFileSync } from "@kreuzberg/node";

const result = extractFileSync("document.pdf");
console.log(result.content);

Parameters: Same as extractFile()

Returns: ExtractionResult

---

Raw Bytes Extraction

extractBytes(data, mimeType, config?): Promise<ExtractionResult>

Extract content from raw bytes (Buffer or Uint8Array) asynchronously.

import { extractBytes } from "@kreuzberg/node";
import { readFile } from "fs/promises";

const data = await readFile("document.pdf");
const result = await extractBytes(data, "application/pdf");
console.log(result.content);

Parameters:

• data: Buffer | Uint8Array — Raw file content
• mimeType: string — MIME type (required)
• config?: ExtractionConfig — Optional configuration

Returns: Promise<ExtractionResult>

extractBytesSync(data, mimeType, config?): ExtractionResult

Extract content from raw bytes synchronously.

import { extractBytesSync } from "@kreuzberg/node";
import { readFileSync } from "fs";

const data = readFileSync("document.pdf");
const result = extractBytesSync(data, "application/pdf");

Parameters: Same as extractBytes()

Returns: ExtractionResult

---

Batch Extraction (Recommended)

For processing multiple documents, batch APIs provide superior performance and memory management.

batchExtractFiles(paths, config?): Promise<ExtractionResult[]>

Extract content from multiple files in parallel (asynchronous).

import { batchExtractFiles } from "@kreuzberg/node";

const files = ["doc1.pdf", "doc2.docx", "doc3.xlsx"];
const results = await batchExtractFiles(files);

results.forEach((result, i) => {
  console.log(`${files[i]}: ${result.content.substring(0, 100)}...`);
});

Parameters:

• paths: string[] — Array of file paths
• config?: ExtractionConfig — Configuration (applied to all files)

Returns: Promise<ExtractionResult[]> — Results in same order as input

batchExtractFilesSync(paths, config?): ExtractionResult[]

Extract content from multiple files synchronously.

import { batchExtractFilesSync } from "@kreuzberg/node";

const files = ["doc1.pdf", "doc2.docx", "doc3.xlsx"];
const results = batchExtractFilesSync(files);

Parameters: Same as batchExtractFiles()

Returns: ExtractionResult[]

batchExtractBytes(dataList, mimeTypes, config?): Promise<ExtractionResult[]>

Extract content from multiple byte arrays in parallel (asynchronous).

import { batchExtractBytes } from "@kreuzberg/node";
import { readFile } from "fs/promises";

const files = ["doc1.pdf", "doc2.docx"];
const dataList = await Promise.all(files.map((f) => readFile(f)));
const mimeTypes = [
  "application/pdf",
  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
];

const results = await batchExtractBytes(dataList, mimeTypes);

Parameters:

• dataList: Uint8Array[] — Array of file contents
• mimeTypes: string[] — MIME types (one per item, must match length)
• config?: ExtractionConfig — Configuration (applied to all items)

Returns: Promise<ExtractionResult[]>

batchExtractBytesSync(dataList, mimeTypes, config?): ExtractionResult[]

Extract content from multiple byte arrays synchronously.

import { batchExtractBytesSync } from "@kreuzberg/node";
import { readFileSync } from "fs";

const dataList = ["doc1.pdf", "doc2.docx"].map((f) => readFileSync(f));
const mimeTypes = [
  "application/pdf",
  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
];

const results = batchExtractBytesSync(dataList, mimeTypes);

Parameters: Same as batchExtractBytes()

Returns: ExtractionResult[]

batchExtractFilesWithConfigs(paths, fileConfigs, config?): Promise<ExtractionResult[]>

Extract multiple files with per-file configuration overrides (asynchronous).

const results = await batchExtractFilesWithConfigs(
  ["report.pdf", "scanned.pdf"],
  [null, { forceOcr: true, ocr: { backend: "tesseract", language: "deu" } }],
);

Parameters:

• paths: string[] — File paths
• fileConfigs: (FileExtractionConfig | null)[] — Per-file configs (null = use batch defaults)
• config?: ExtractionConfig — Batch-level configuration

batchExtractFilesWithConfigsSync(paths, fileConfigs, config?): ExtractionResult[]

Synchronous variant.

batchExtractBytesWithConfigs(dataList, mimeTypes, fileConfigs, config?): Promise<ExtractionResult[]>

Extract multiple byte arrays with per-file overrides (asynchronous).

batchExtractBytesWithConfigsSync(dataList, mimeTypes, fileConfigs, config?): ExtractionResult[]

Synchronous variant.

---

Worker Pool APIs

Worker pools enable concurrent extraction using Node.js worker threads for CPU-bound processing.

createWorkerPool(size?): WorkerPool

Create a worker pool for concurrent extraction.

import { createWorkerPool } from "@kreuzberg/node";

// Create pool with default size (number of CPU cores)
const pool = createWorkerPool();

// Create pool with specific size
const pool4 = createWorkerPool(4);

Parameters:

• size?: number — Number of workers (defaults to CPU core count)

Returns: WorkerPool — Opaque handle for use with worker extraction functions

extractFileInWorker(pool, filePath, mimeType?, config?): Promise<ExtractionResult>

Extract a single file using a worker from the pool.

import { createWorkerPool, extractFileInWorker, closeWorkerPool } from "@kreuzberg/node";

const pool = createWorkerPool(4);

try {
  const files = ["doc1.pdf", "doc2.docx", "doc3.xlsx"];
  const results = await Promise.all(files.map((f) => extractFileInWorker(pool, f)));

  results.forEach((r, i) => {
    console.log(`${files[i]}: ${r.content.substring(0, 100)}...`);
  });
} finally {
  await closeWorkerPool(pool);
}

Parameters:

• pool: WorkerPool — Worker pool instance
• filePath: string — File path
• mimeType?: string | null — Optional MIME type
• config?: ExtractionConfig — Optional configuration

Returns: Promise<ExtractionResult>

batchExtractFilesInWorker(pool, paths, config?): Promise<ExtractionResult[]>

Extract multiple files using the worker pool for concurrent processing.

import { createWorkerPool, batchExtractFilesInWorker, closeWorkerPool } from "@kreuzberg/node";

const pool = createWorkerPool(4);

try {
  const files = ["invoice1.pdf", "invoice2.pdf", "invoice3.pdf"];
  const results = await batchExtractFilesInWorker(pool, files, {
    ocr: { backend: "tesseract", language: "eng" },
  });

  const total = results.reduce((sum, r) => sum + extractAmount(r.content), 0);
  console.log(`Total: $${total}`);
} finally {
  await closeWorkerPool(pool);
}

Parameters:

• pool: WorkerPool — Worker pool instance
• paths: string[] — File paths
• config?: ExtractionConfig — Configuration (applied to all files)

Returns: Promise<ExtractionResult[]>

getWorkerPoolStats(pool): WorkerPoolStats

Get statistics about a worker pool.

import { createWorkerPool, getWorkerPoolStats } from "@kreuzberg/node";

const pool = createWorkerPool(4);
const stats = getWorkerPoolStats(pool);

console.log(`Pool size: ${stats.size}`);
console.log(`Active workers: ${stats.activeWorkers}`);
console.log(`Queued tasks: ${stats.queuedTasks}`);

Parameters:

• pool: WorkerPool — Worker pool instance

Returns: WorkerPoolStats

closeWorkerPool(pool): Promise<void>

Close a worker pool and shut down all worker threads.

import { createWorkerPool, closeWorkerPool } from "@kreuzberg/node";

const pool = createWorkerPool(4);

try {
  // Use pool
} finally {
  await closeWorkerPool(pool);
}

Parameters:

• pool: WorkerPool — Worker pool instance to close

Returns: Promise<void>

---

Configuration Interface

ExtractionConfig

Main configuration object controlling extraction behavior.

interface ExtractionConfig {
  // Caching and processing
  useCache?: boolean; // Default: true
  enableQualityProcessing?: boolean; // Default: false

  // OCR configuration
  ocr?: OcrConfig; // OCR settings
  forceOcr?: boolean; // Default: false

  // Document processing
  chunking?: ChunkingConfig; // Break into chunks
  images?: ImageExtractionConfig; // Image extraction
  pdfOptions?: PdfConfig; // PDF-specific options
  tokenReduction?: TokenReductionConfig; // Token optimization
  languageDetection?: LanguageDetectionConfig; // Language detection
  postprocessor?: PostProcessorConfig; // Post-processing
  htmlOptions?: HtmlConversionOptions; // HTML conversion
  keywords?: KeywordConfig; // Keyword extraction
  pages?: PageExtractionConfig; // Page extraction

  // Output control
  maxConcurrentExtractions?: number; // Default: 4
  outputFormat?: "plain" | "markdown" | "djot" | "html"; // Default: 'plain'
  resultFormat?: "unified" | "element_based"; // Default: 'unified'
}

FileExtractionConfig

Per-file overrides for batch operations. All fields optional (omitted = use batch default).

interface FileExtractionConfig {
  enableQualityProcessing?: boolean;
  ocr?: OcrConfig;
  forceOcr?: boolean;
  chunking?: ChunkingConfig;
  images?: ImageExtractionConfig;
  pdfOptions?: PdfConfig;
  tokenReduction?: TokenReductionConfig;
  languageDetection?: LanguageDetectionConfig;
  pages?: PageExtractionConfig;
  keywords?: KeywordConfig;
  postprocessor?: PostProcessorConfig;
  outputFormat?: "plain" | "markdown" | "djot" | "html";
  resultFormat?: "unified" | "element_based";
  includeDocumentStructure?: boolean;
}

Excluded (batch-level only): maxConcurrentExtractions, useCache, securityLimits.

ChunkingConfig

Configuration for breaking documents into chunks (useful for RAG and vector databases).

interface ChunkingConfig {
  maxChars?: number; // Max characters per chunk (default: 4096)
  maxOverlap?: number; // Overlap between chunks (default: 512)
  chunkSize?: number; // Alternative unit (mutually exclusive with maxChars)
  chunkOverlap?: number; // Alternative unit (mutually exclusive with maxOverlap)
  preset?: string; // Named preset ('default', 'aggressive', 'minimal')
  embedding?: Record<string, unknown>; // Embedding config
  enabled?: boolean; // Enable chunking (default: true when config provided)
}

Key Point: Use maxChars and maxOverlap, NOT maxCharacters or overlap.

OcrConfig

Configuration for optical character recognition.

interface OcrConfig {
  backend: string; // OCR backend name (e.g., 'tesseract')
  language?: string; // Language code (e.g., 'eng', 'deu')
  tesseractConfig?: TesseractConfig;
}

interface TesseractConfig {
  psm?: number; // Page Segmentation Mode (0-13)
  enableTableDetection?: boolean;
  tesseditCharWhitelist?: string; // Character whitelist
}

ImageExtractionConfig

Configuration for extracting and optimizing images.

interface ImageExtractionConfig {
  extractImages?: boolean; // Default: true
  targetDpi?: number; // Target DPI (default: 150)
  maxImageDimension?: number; // Max width/height in pixels (default: 2000)
  autoAdjustDpi?: boolean; // Auto-adjust DPI (default: true)
  minDpi?: number; // Minimum DPI (default: 72)
  maxDpi?: number; // Maximum DPI (default: 300)
}

PdfConfig

PDF-specific extraction options.

interface PdfConfig {
  extractImages?: boolean; // Default: true
  passwords?: string[]; // Passwords for encrypted PDFs
  extractMetadata?: boolean; // Default: true
  hierarchy?: HierarchyConfig; // Hierarchy extraction
}

LanguageDetectionConfig

Configuration for automatic language detection.

interface LanguageDetectionConfig {
  enabled?: boolean; // Default: true
  minConfidence?: number; // Threshold 0.0-1.0 (default: 0.5)
  detectMultiple?: boolean; // Detect multiple languages (default: false)
}

TokenReductionConfig

Configuration for optimizing token usage.

interface TokenReductionConfig {
  mode?: string; // 'aggressive' or 'conservative' (default: 'conservative')
  preserveImportantWords?: boolean; // Default: true
}

KeywordConfig

Configuration for keyword extraction.

interface KeywordConfig {
  algorithm?: "yake" | "rake"; // Default: 'yake'
  maxKeywords?: number; // Maximum keywords (default: 10)
  minScore?: number; // Minimum relevance score (default: 0.1)
  ngramRange?: [number, number]; // N-gram range (default: [1, 3])
  language?: string; // Language code (default: 'en')
  yakeParams?: YakeParams;
  rakeParams?: RakeParams;
}

PageExtractionConfig

Configuration for page-level content tracking.

interface PageExtractionConfig {
  extractPages?: boolean; // Extract as separate pages array
  insertPageMarkers?: boolean; // Insert page markers in content
  markerFormat?: string; // Marker format with {page_num} placeholder
}

HtmlConversionOptions

Configuration for HTML to Markdown conversion.

interface HtmlConversionOptions {
  headingStyle?: "atx" | "underlined" | "atx_closed";
  listIndentType?: "spaces" | "tabs";
  listIndentWidth?: number;
  bullets?: string;
  strongEmSymbol?: string;
  escapeAsterisks?: boolean;
  escapeUnderscores?: boolean;
  escapeMisc?: boolean;
  escapeAscii?: boolean;
  codeLanguage?: string;
  autolinks?: boolean;
  defaultTitle?: boolean;
  brInTables?: boolean;
  hocrSpatialTables?: boolean;
  highlightStyle?: "double_equal" | "html" | "bold" | "none";
  extractMetadata?: boolean;
  whitespaceMode?: "normalized" | "strict";
  stripNewlines?: boolean;
  wrap?: boolean;
  wrapWidth?: number;
  convertAsInline?: boolean;
  subSymbol?: string;
  supSymbol?: string;
  newlineStyle?: "spaces" | "backslash";
  codeBlockStyle?: "indented" | "backticks" | "tildes";
  keepInlineImagesIn?: string[];
  encoding?: string;
  debug?: boolean;
  stripTags?: string[];
  preserveTags?: string[];
  preprocessing?: HtmlPreprocessingOptions;
}

---

Result Types

ExtractionResult

Complete extraction result from document processing.

interface ExtractionResult {
  // Main content
  content: string;

  // Document type
  mimeType: string;

  // Metadata (format-specific)
  metadata: Metadata;

  // Extracted structures
  tables: Table[];

  // Optional processed data
  detectedLanguages: string[] | null;
  chunks: Chunk[] | null; // From chunking config
  images: ExtractedImage[] | null; // From image extraction
  elements?: Element[] | null; // From element_based result format
  pages?: PageContent[] | null; // From page extraction
  extractedKeywords?: ExtractedKeyword[] | null; // Extracted keywords with scores
  qualityScore?: number | null; // Overall extraction quality (0.0-1.0)
  processingWarnings?: ProcessingWarning[]; // Non-fatal warnings from pipeline
}

Table

Extracted table data with cell structure.

interface Table {
  cells: string[][]; // 2D array of cell contents (rows × columns)
  markdown: string; // Markdown representation
  pageNumber: number; // 1-indexed page number
}

Chunk

Text chunk for RAG or vector database indexing.

interface Chunk {
  content: string;
  embedding?: number[] | null; // Vector embedding if computed
  metadata: ChunkMetadata;
}

interface ChunkMetadata {
  byteStart: number; // UTF-8 byte offset in original text
  byteEnd: number; // UTF-8 byte offset
  tokenCount?: number | null;
  chunkIndex: number; // Zero-based index
  totalChunks: number; // Total number of chunks
  firstPage?: number | null; // 1-indexed, if page tracking enabled
  lastPage?: number | null;
}

ExtractedImage

Image extracted from document.

interface ExtractedImage {
  data: Uint8Array; // Raw image bytes
  format: string; // Format (e.g., 'png', 'jpeg', 'tiff')
  imageIndex: number; // Sequential index (0-indexed)
  pageNumber?: number | null;
  width?: number | null;
  height?: number | null;
  colorspace?: string | null;
  bitsPerComponent?: number | null;
  isMask: boolean;
  description?: string | null;
  ocrResult?: ExtractionResult | null; // OCR result if processed
}

PageContent

Per-page content when page extraction is enabled.

interface PageContent {
  pageNumber: number; // 1-indexed
  content: string; // Page text content
  tables: Table[]; // Tables on this page
  images: ExtractedImage[]; // Images on this page
}

ExtractedKeyword

Extracted keyword with relevance score and position information.

interface ExtractedKeyword {
  text: string; // Keyword text
  score: number; // Relevance score (0.0-1.0)
  algorithm: string; // Algorithm used ("tfidf", "textrank", "yake", etc.)
  positions?: number[] | null; // Character positions in content (if available)
}

ProcessingWarning

Non-fatal warning encountered during document processing.

interface ProcessingWarning {
  source: string; // Component that generated the warning
  message: string; // Warning message describing the issue
}

Metadata

Extraction result metadata (format-specific).

interface Metadata {
  // Common fields
  language?: string | null;
  date?: string | null;
  subject?: string | null;
  format_type?:
    | "pdf"
    | "excel"
    | "email"
    | "pptx"
    | "archive"
    | "image"
    | "xml"
    | "text"
    | "html"
    | "ocr";

  // PDF metadata
  title?: string | null;
  author?: string | null;
  creator?: string | null;
  producer?: string | null;
  creation_date?: string | null;
  modification_date?: string | null;
  page_count?: number;

  // Excel metadata
  sheet_count?: number;
  sheet_names?: string[];

  // Email metadata
  from_email?: string | null;
  from_name?: string | null;
  to_emails?: string[];
  cc_emails?: string[];
  bcc_emails?: string[];
  message_id?: string | null;
  attachments?: string[];

  // Image metadata
  width?: number;
  height?: number;
  exif?: Record<string, string>;

  // OCR metadata
  psm?: number;
  output_format?: string;
  table_count?: number;

  // HTML metadata
  canonical_url?: string | null;
  html_language?: string | null;
  text_direction?: "ltr" | "rtl" | "auto" | null;
  open_graph?: Record<string, string>;
  twitter_card?: Record<string, string>;
  meta_tags?: Record<string, string>;
  html_headers?: HeaderMetadata[];
  html_links?: LinkMetadata[];
  html_images?: HtmlImageMetadata[];
  structured_data?: StructuredData[];

  // Text metadata
  line_count?: number;
  word_count?: number;
  character_count?: number;
  headers?: string[] | null;
  links?: [string, string][] | null;
  code_blocks?: [string, string][] | null;

  // Page structure
  page_structure?: PageStructure | null;

  // Additional typed fields
  category?: string | null;
  tags?: string[];
  document_version?: string | null;
  abstract_text?: string | null;

  // Custom fields from postprocessors
  [key: string]: unknown;
}

---

Error Handling

Error Classes

import {
  KreuzbergError,
  ParsingError,
  OcrError, // Note: camelCase, not "OCRError"
  ValidationError,
  MissingDependencyError,
  CacheError,
  ImageProcessingError,
  PluginError,
  ErrorCode,
} from "@kreuzberg/node";

Error Hierarchy:

• KreuzbergError — Base class for all Kreuzberg errors
• ParsingError — Document format invalid or corrupted
• OcrError — OCR processing failed
• ValidationError — Extraction validation failed
• MissingDependencyError — Required dependency unavailable
• CacheError — Cache operation failed
• ImageProcessingError — Image extraction or processing failed
• PluginError — Plugin registration or execution failed

Error Diagnostics

import {
  classifyError,
  getErrorCodeDescription,
  getErrorCodeName,
  getLastErrorCode,
  getLastPanicContext,
} from "@kreuzberg/node";

try {
  const result = await extractFile("document.pdf");
} catch (error) {
  const classification = classifyError(error.message);
  console.log(`Error code: ${getErrorCodeName(classification.code)}`);
  console.log(`Description: ${getErrorCodeDescription(classification.code)}`);
  console.log(`Confidence: ${classification.confidence}`);
}

ErrorCode Enum

enum ErrorCode {
  Success = 0,
  GenericError = 1,
  Panic = 2,
  InvalidArgument = 3,
  IoError = 4,
  ParsingError = 5,
  OcrError = 6,
  MissingDependency = 7,
}

---

Plugin System

Post-Processors

Custom post-processors can enrich extraction results without failing the extraction if they encounter errors.

registerPostProcessor(processor): void

Register a custom post-processor.

import { registerPostProcessor, extractFile } from "@kreuzberg/node";

const processor = {
  name() {
    return "my_processor";
  },

  async process(result) {
    // Enrich result with custom metadata
    result.metadata["custom_field"] = "value";
    return result;
  },

  processingStage() {
    return "late"; // 'early', 'middle', or 'late'
  },

  async initialize() {
    // Called once when registered
  },

  async shutdown() {
    // Called when unregistered
  },
};

registerPostProcessor(processor);
const result = await extractFile("document.pdf");

unregisterPostProcessor(name): void

Remove a registered post-processor.

import { unregisterPostProcessor } from "@kreuzberg/node";

unregisterPostProcessor("my_processor");

listPostProcessors(): string[]

List all registered post-processor names.

import { listPostProcessors } from "@kreuzberg/node";

const processors = listPostProcessors();
console.log("Registered processors:", processors);

clearPostProcessors(): void

Unregister all post-processors.

import { clearPostProcessors } from "@kreuzberg/node";

clearPostProcessors();

Validators

Custom validators check extraction results and fail the extraction if validation fails (unlike post-processors).

registerValidator(validator): void

Register a custom validator.

import { registerValidator, extractFile } from "@kreuzberg/node";

const validator = {
  name() {
    return "content_length_validator";
  },

  validate(result) {
    if (result.content.length < 10) {
      throw new Error("Content too short");
    }
  },

  priority() {
    return 100; // Higher = runs first
  },

  shouldValidate(result) {
    return result.mimeType === "application/pdf"; // Conditional validation
  },

  async initialize() {
    // Called once when registered
  },

  async shutdown() {
    // Called when unregistered
  },
};

registerValidator(validator);
const result = await extractFile("document.pdf");

unregisterValidator(name): void

Remove a registered validator.

import { unregisterValidator } from "@kreuzberg/node";

unregisterValidator("content_length_validator");

listValidators(): string[]

List all registered validator names.

import { listValidators } from "@kreuzberg/node";

const validators = listValidators();

clearValidators(): void

Unregister all validators.

import { clearValidators } from "@kreuzberg/node";

clearValidators();

OCR Backends

Custom OCR backends can be registered to handle image text extraction.

registerOcrBackend(backend): void

Register a custom OCR backend.

import { registerOcrBackend, extractFile } from "@kreuzberg/node";

const backend = {
  name() {
    return "my-ocr";
  },

  supportedLanguages() {
    return ["eng", "deu", "fra"];
  },

  async processImage(imageBytes, language) {
    // imageBytes: Uint8Array or Base64 string
    const buffer =
      typeof imageBytes === "string" ? Buffer.from(imageBytes, "base64") : Buffer.from(imageBytes);

    // Process and extract text
    return {
      content: "extracted text",
      mime_type: "text/plain",
      metadata: { confidence: 0.95, language },
      tables: [],
    };
  },

  async initialize() {
    // Load models, setup resources
  },

  async shutdown() {
    // Cleanup resources
  },
};

registerOcrBackend(backend);

GutenOcrBackend

Built-in OCR backend implementation using Guten-OCR.

import { GutenOcrBackend, registerOcrBackend, extractFile } from "@kreuzberg/node";

const backend = new GutenOcrBackend();
await backend.initialize();
registerOcrBackend(backend);

const result = await extractFile("scanned.pdf", null, {
  ocr: { backend: "guten-ocr", language: "eng" },
});

unregisterOcrBackend(name): void

Remove a registered OCR backend.

import { unregisterOcrBackend } from "@kreuzberg/node";

unregisterOcrBackend("my-ocr");

listOcrBackends(): string[]

List all registered OCR backend names.

import { listOcrBackends } from "@kreuzberg/node";

const backends = listOcrBackends();

clearOcrBackends(): void

Unregister all OCR backends.

import { clearOcrBackends } from "@kreuzberg/node";

clearOcrBackends();

---

MIME Type Utilities

detectMimeType(data): string | null

Detect MIME type from file content (magic bytes).

import { detectMimeType } from "@kreuzberg/node";
import { readFileSync } from "fs";

const data = readFileSync("document");
const mimeType = detectMimeType(data);
console.log(`Detected MIME type: ${mimeType}`);

detectMimeTypeFromPath(filePath): string | null

Detect MIME type from file extension.

import { detectMimeTypeFromPath } from "@kreuzberg/node";

const mimeType = detectMimeTypeFromPath("document.pdf");
console.log(`MIME type: ${mimeType}`); // 'application/pdf'

getExtensionsForMime(mimeType): string[]

Get file extensions for a MIME type.

import { getExtensionsForMime } from "@kreuzberg/node";

const extensions = getExtensionsForMime("application/pdf");
console.log(`Extensions: ${extensions}`); // ['.pdf']

validateMimeType(mimeType): boolean

Check if a MIME type is valid.

import { validateMimeType } from "@kreuzberg/node";

if (validateMimeType("application/pdf")) {
  console.log("Valid MIME type");
}

---

Configuration Loading

ExtractionConfig.fromFile(filePath): ExtractionConfig

Load extraction configuration from a file (JSON, YAML, or TOML).

import { ExtractionConfig, extractFile } from "@kreuzberg/node";

const config = ExtractionConfig.fromFile("./kreuzberg.toml");
const result = await extractFile("document.pdf", null, config);

ExtractionConfig.discover(): ExtractionConfig | null

Auto-discover extraction configuration file in current and parent directories.

import { ExtractionConfig, extractFile } from "@kreuzberg/node";

// Searches for kreuzberg.{toml,yaml,json} in current directory and parents
const config = ExtractionConfig.discover();
if (config) {
  const result = await extractFile("document.pdf", null, config);
}

---

Embeddings

getEmbeddingPreset(name): EmbeddingPreset | null

Get a named embedding model preset.

import { getEmbeddingPreset } from "@kreuzberg/node";

const preset = getEmbeddingPreset("default");
if (preset) {
  console.log(`Model: ${preset.modelName}`);
  console.log(`Dimensions: ${preset.dimensions}`);
}

listEmbeddingPresets(): string[]

List all available embedding presets.

import { listEmbeddingPresets } from "@kreuzberg/node";

const presets = listEmbeddingPresets();
console.log("Available presets:", presets);

EmbeddingPreset

Type definition for embedding model presets.

interface EmbeddingPreset {
  name: string; // Preset name (e.g., "fast", "balanced", "quality", "multilingual")
  chunkSize: number; // Recommended chunk size in characters
  overlap: number; // Recommended overlap in characters
  modelName: string; // Model identifier (e.g., "AllMiniLML6V2Q", "BGEBaseENV15")
  dimensions: number; // Embedding vector dimensions
  description: string; // Human-readable description
}

---

Plugin Protocols

PostProcessorProtocol

Interface for custom post-processors.

interface PostProcessorProtocol {
  name(): string;

  process(result: ExtractionResult): ExtractionResult | Promise<ExtractionResult>;

  processingStage?(): ProcessingStage; // 'early' | 'middle' | 'late'

  initialize?(): void | Promise<void>;

  shutdown?(): void | Promise<void>;
}

ValidatorProtocol

Interface for custom validators.

interface ValidatorProtocol {
  name(): string;

  validate(result: ExtractionResult): void | Promise<void>;

  priority?(): number; // Higher = runs first

  shouldValidate?(result: ExtractionResult): boolean;

  initialize?(): void | Promise<void>;

  shutdown?(): void | Promise<void>;
}

OcrBackendProtocol

Interface for custom OCR backends.

interface OcrBackendProtocol {
  name(): string;

  supportedLanguages(): string[];

  processImage(
    imageBytes: Uint8Array | string,
    language: string,
  ): Promise<{
    content: string;
    mime_type: string;
    metadata: Record<string, unknown>;
    tables: unknown[];
  }>;

  initialize?(): void | Promise<void>;

  shutdown?(): void | Promise<void>;
}

---

Supported Document Formats

• Documents: PDF, DOCX, PPTX, XLSX, DOC, PPT
• Text: Markdown, Plain Text, XML, JSON, YAML, TOML
• Web: HTML (converted to Markdown)
• Email: EML, MSG
• Images: PNG, JPEG, TIFF (with OCR support)
• Archives: ZIP, TAR, GZIP (file listing)

---

Registry Functions

Document Extractors

import {
  listDocumentExtractors,
  unregisterDocumentExtractor,
  clearDocumentExtractors,
} from "@kreuzberg/node";

// List registered extractors
const extractors = listDocumentExtractors();

// Unregister a specific extractor
unregisterDocumentExtractor("pdf");

// Clear all extractors
clearDocumentExtractors();

---

Type Exports

All types are exported from @kreuzberg/node:

export type {
  Chunk,
  ChunkingConfig,
  ExtractionConfig,
  ExtractionResult,
  ExtractedImage,
  KeywordConfig,
  LanguageDetectionConfig,
  OcrBackendProtocol,
  OcrConfig,
  PageContent,
  PageExtractionConfig,
  PdfConfig,
  PostProcessorProtocol,
  Table,
  TokenReductionConfig,
  ValidatorProtocol,
  WorkerPool,
  WorkerPoolStats,
  EmbeddingPreset,
  // ... and many more
};

---

Best Practices

1. Use batch APIs for multiple documents: batchExtractFiles() provides superior performance vs. calling extractFile() in a loop.

2. Enable chunking for RAG/vector DB: Set chunking config to automatically break documents into overlapping chunks.

3. Use worker pools for high-concurrency scenarios: Distribute CPU-bound work across multiple threads for 4+ concurrent extractions.

4. Configure language detection: Enable automatic language detection for multilingual documents.

5. Register validators early: Set up validators before calling extraction functions to catch quality issues immediately.

6. Use specific MIME types: Provide explicit MIME types when available to avoid detection overhead.

7. Clean up resources: Always call closeWorkerPool() when done to prevent resource leaks.

8. Handle extraction errors gracefully: Catch specific error types (ParsingError, OcrError, etc.) for appropriate error handling.

---

Version

Package Version: 4.2.14

Language Bindings Reference

Kreuzberg provides native bindings for multiple programming languages, each with precompiled binaries for x86_64 and aarch64 on Linux and macOS. This reference covers installation and basic usage for each binding.

Go

Installation:

go get github.com/kreuzberg-dev/kreuzberg/packages/go/v5

Basic Extraction:

package main

import (
    "context"
    "fmt"
    "github.com/kreuzberg-dev/kreuzberg/packages/go/v5/kreuzberg"
)

func main() {
    ctx := context.Background()
    result, err := kreuzberg.ExtractFile(ctx, "document.pdf", nil)
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Content)
}

See the Go binding documentation for complete API reference.

Ruby

Installation:

gem install kreuzberg

Or in your Gemfile:

gem 'kreuzberg'

Basic Extraction:

require 'kreuzberg'

result = Kreuzberg.extract_file_sync('document.pdf')
puts result.content

See the Ruby binding documentation for complete API reference.

Java

Installation: Add to your Maven pom.xml:

<dependency>
    <groupId>dev.kreuzberg</groupId>
    <artifactId>kreuzberg</artifactId>
    <version>4.2.x</version>
</dependency>

Basic Extraction:

import dev.kreuzberg.Kreuzberg;
import dev.kreuzberg.ExtractionResult;

public class Example {
    public static void main(String[] args) throws Exception {
        ExtractionResult result = Kreuzberg.extractFile("document.pdf");
        System.out.println(result.getContent());
    }
}

See the Java binding documentation for complete API reference.

C

Installation:

dotnet add package Kreuzberg

Basic Extraction:

using Kreuzberg;

var result = KreuzbergClient.ExtractFileSync("document.pdf");
Console.WriteLine(result.Content);

See the C# binding documentation for complete API reference.

PHP

Installation:

composer require kreuzberg/kreuzberg

Basic Extraction:

<?php
require 'vendor/autoload.php';

use Kreuzberg\Kreuzberg;

$kreuzberg = new Kreuzberg();
$result = $kreuzberg->extractFile('document.pdf');
echo $result->content;

See the PHP binding documentation for complete API reference.

Elixir

Installation: Add to your mix.exs dependencies:

def deps do
  [
    kreuzberg: "~> 4.2"
  ]
end

Basic Extraction:

{:ok, result} = Kreuzberg.extract_file("document.pdf")
IO.puts(result.content)

See the Elixir binding documentation for complete API reference.

WebAssembly (WASM)

Installation:

npm install @kreuzberg/wasm

Basic Extraction:

import { extractBytes } from "@kreuzberg/wasm";

const fileData = await fs.promises.readFile("document.pdf");
const result = await extractBytes(fileData, "application/pdf");
console.log(result.content);

Supports browsers, Deno, and Cloudflare Workers.

See the WASM binding documentation for complete API reference.

Docker

Installation: Pull the official image from GitHub Container Registry:

docker pull ghcr.io/kreuzberg-dev/kreuzberg

API Server Mode:

docker run -p 8000:8000 ghcr.io/kreuzberg-dev/kreuzberg serve --host 0.0.0.0

CLI Mode:

docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg extract /data/document.pdf

MCP Server Mode:

docker run -i ghcr.io/kreuzberg-dev/kreuzberg mcp

Image sizes:

• Core image: 1.0-1.3GB
• Full image: ~1.0-1.3GB

See the Docker guide for deployment details.

Platform Support

All language bindings include precompiled binaries for x86_64 and aarch64 on Linux and macOS. Windows support varies by binding. Refer to the main README for platform compatibility matrix.

Supported Formats Reference

Kreuzberg supports 91+ file formats across 8 major categories with intelligent format detection and comprehensive metadata extraction. All formats support text and metadata extraction. Additional capabilities like OCR and table detection are noted per format.

Office Documents

Word Processing

Spreadsheets

Presentations

PDF

eBooks

Database

Hangul

Images (OCR-Enabled)

Raster Images

Advanced Image Formats

Vector Graphics

Web & Data

Markup & Structured Text

Structured Data Formats

Text & Markup Languages

Email & Archives

Email Formats

Archive Formats

Academic & Scientific

Citation Formats

Scientific & Technical Formats

Documentation Formats

Format Capabilities Summary

Text Extraction

All 85+ formats support full or partial text extraction. Document structure and encoding are automatically detected.

Metadata Support

Comprehensive metadata extraction includes:

• Document properties (title, author, subject, creation date, modification date)
• Format-specific metadata (page count, dimensions, encoding, language)
• EXIF data (for images)
• Document statistics (word count, character count)

OCR (Optical Character Recognition)

OCR is available for image formats:

• Raster Images: PNG, JPEG, GIF, WebP, BMP, TIFF
• Advanced Formats: JPEG 2000, JBIG2, PNM/PBM/PGM/PPM
• Configurable Backends: Tesseract (all languages), EasyOCR, PaddleOCR (Python), Guten (Node.js)

Table Detection

Smart table detection and reconstruction available for:

• PDF documents (native tables and scanned content with OCR)
• Office documents (Excel, Word)
• Images (via OCR backends)
• HTML/XML (from markup structure)

Archive & Nested Document Support

Archives and nested formats support file listing and sequential extraction:

• ZIP, TAR, TGZ, 7Z archives
• Email attachments
• Nested archives within archives

Getting Started

For language-specific examples and detailed API documentation, see the API Reference.

For OCR configuration and backend selection, see the OCR Backends Guide.

For comprehensive format details and format detection, see the Complete Format Reference.