R API Reference

Complete reference for the Kreuzberg R API.

Installation

Install from the R-universe repository:

R

install.packages("kreuzberg", repos = "https://kreuzberg-dev.r-universe.dev")

Or install from source using remotes:

R

remotes::install_github("kreuzberg-dev/kreuzberg-lts", subdir = "packages/r")

System Requirements:

• R >= 4.2
• Rust toolchain (cargo, rustc >= 1.91) for building from source
• Supported platforms: Linux (x64, arm64), macOS (Apple Silicon)

---

Core Functions

Batch_extract_bytes()

Extract content from multiple raw byte arrays (asynchronous via Tokio runtime).

Signature:

R

batch_extract_bytes(data_list, mime_types, config = NULL) -> list of kreuzberg_result

Parameters:

Same as batch_extract_bytes_sync().

Returns:

• List of kreuzberg_result objects

---

Batch_extract_bytes_sync()

Extract content from multiple raw byte arrays (synchronous).

Signature:

R

batch_extract_bytes_sync(data_list, mime_types, config = NULL) -> list of kreuzberg_result

Parameters:

Parameter	Type	Description
data_list	list of raw	List of binary data (raw vectors)
mime_types	character	MIME types corresponding to each byte array
config	list, NULL	Extraction configuration

Returns:

• List of kreuzberg_result objects

Example:

R

library(kreuzberg)

pdf_data <- readBin("invoice.pdf", what = "raw", n = file.size("invoice.pdf"))
docx_data <- readBin("report.docx", what = "raw", n = file.size("report.docx"))

data_list <- list(pdf_data, docx_data)
mime_types <- c("application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document")

results <- batch_extract_bytes_sync(data_list, mime_types)

for (i in seq_along(results)) {
  cat(sprintf("Document %d: %d characters\n", i, nchar(results[[i]]$content)))
}

---

Batch_extract_files()

Extract content from multiple files in parallel (asynchronous via Tokio runtime).

Signature:

R

batch_extract_files(paths, config = NULL) -> list of kreuzberg_result

Parameters:

Same as batch_extract_files_sync().

Returns:

• List of kreuzberg_result objects

---

Batch_extract_files_sync()

Extract content from multiple files in parallel (synchronous).

Signature:

R

batch_extract_files_sync(paths, config = NULL) -> list of kreuzberg_result

Parameters:

Parameter	Type	Description
paths	character	Vector of file paths to extract
config	list, NULL	Extraction configuration applied to all files

Returns:

• List of kreuzberg_result objects

Example:

R

library(kreuzberg)

paths <- c("doc1.pdf", "doc2.docx", "doc3.xlsx")
results <- batch_extract_files_sync(paths)

for (i in seq_along(results)) {
  cat(sprintf("%s: %d characters\n", paths[i], nchar(results[[i]]$content)))
}

---

Extract_bytes()

Extract content from raw bytes (asynchronous via Tokio runtime).

Signature:

R

extract_bytes(data, mime_type, config = NULL) -> kreuzberg_result

Parameters:

Same as extract_bytes_sync().

Returns:

• kreuzberg_result: Extraction result object

---

Extract_bytes_sync()

Extract content from raw bytes (synchronous).

Signature:

R

extract_bytes_sync(data, mime_type, config = NULL) -> kreuzberg_result

Parameters:

Parameter	Type	Description
data	raw	Binary data to extract (raw vector)
mime_type	character	MIME type of the data (required for format detection)
config	list, NULL	Extraction configuration

Returns:

• kreuzberg_result: Extraction result object

Example:

R

library(kreuzberg)

data <- readBin("document.pdf", what = "raw", n = file.size("document.pdf"))
result <- extract_bytes_sync(data, "application/pdf")
cat(result$content)

---

Extract_file()

Extract content from a file (asynchronous via Tokio runtime).

Note: R does not have native async/await. This function internally uses a blocking Tokio runtime. For background processing, run in a separate R process or use a thread pool.

Signature:

R

extract_file(path, mime_type = NULL, config = NULL) -> kreuzberg_result

Parameters:

Same as extract_file_sync().

Returns:

• kreuzberg_result: Extraction result object

Example:

R

library(kreuzberg)

# Equivalent to extract_file_sync in R
result <- extract_file("document.pdf")
cat(result$content)

---

Extract_file_sync()

Extract content from a file (synchronous).

Signature:

R

extract_file_sync(path, mime_type = NULL, config = NULL) -> kreuzberg_result

Parameters:

Parameter	Type	Description
path	character	Path to the file to extract
mime_type	character, NULL	Optional MIME type hint. If NULL, MIME type is auto-detected
config	list, NULL	Extraction configuration. Uses defaults if NULL

Returns:

• kreuzberg_result: Extraction result object (S3 class inheriting from list)

Raises:

• ValidationError: Input validation failed
• ParsingError: Document parsing failed
• FileNotFoundError: File does not exist
• UnsupportedFormatError: Document format not supported
• ExtractionError: General extraction failure

Example - Basic usage:

R

library(kreuzberg)

result <- extract_file_sync("document.pdf")
cat("Content:\n", result$content, "\n")
cat("Pages:", page_count(result), "\n")

Example - With configuration:

R

library(kreuzberg)

config <- extraction_config(
  ocr = ocr_config(backend = "tesseract", language = "eng")
)
result <- extract_file_sync("scanned.pdf", config = config)

Example - With explicit MIME type:

R

library(kreuzberg)

result <- extract_file_sync("document.pdf", mime_type = "application/pdf")

---

Configuration

Chunking_config()

Create text chunking configuration.

Signature:

R

chunking_config(max_characters = 1000L, overlap = 200L, ...) -> list

Parameters:

Parameter	Type	Description
max_characters	integer	Maximum characters per chunk. Default: 1000
overlap	integer	Overlap between chunks. Default: 200
…		Additional chunking options

Returns:

• Named list with chunking configuration

Example:

R

config <- extraction_config(
  chunking = chunking_config(max_characters = 2000L, overlap = 500L)
)

---

Discover()

Search for kreuzberg.toml configuration file in current and parent directories.

Signature:

R

discover() -> list or NULL

Returns:

• Named list with configuration if found, NULL otherwise

Example:

R

config <- discover()
if (!is.null(config)) {
  result <- extract_file_sync("document.pdf", config = config)
}

---

Extraction_config()

Create an extraction configuration object.

Signature:

R

extraction_config(
  chunking = NULL,
  enable_quality_processing = NULL,
  force_ocr = FALSE,
  html_options = NULL,
  images = NULL,
  include_document_structure = NULL,
  keywords = NULL,
  language_detection = NULL,
  layout = NULL,
  max_concurrent_extractions = NULL,
  ocr = NULL,
  output_format = NULL,
  pages = NULL,
  pdf_options = NULL,
  postprocessor = NULL,
  result_format = NULL,
  security_limits = NULL,
  token_reduction = NULL,
  use_cache = NULL,
  ...
) -> list

Parameters:

Parameter	Type	Description
chunking	list, NULL	Text chunking options (see chunking_config())
enable_quality_processing	logical, NULL	Enable quality processing enhancements
force_ocr	logical	Force OCR on all documents regardless of document type
html_options	list, NULL	HTML-specific options
images	list, NULL	Image extraction options
include_document_structure	logical, NULL	Include hierarchical document structure in results
keywords	list, NULL	Keyword extraction options
language_detection	list, NULL	Language detection options
layout	list, NULL	Layout detection options
max_concurrent_extractions	integer, NULL	Maximum concurrent extractions for batch operations
ocr	list, NULL	OCR configuration (see ocr_config())
output_format	character, NULL	Output format for extracted content (‘plain’, ‘markdown’, ‘djot’, ‘html’)
pages	list, NULL	Page extraction options
pdf_options	list, NULL	PDF-specific options
postprocessor	character, NULL	Post-processor name
result_format	character, NULL	Result format (‘unified’, ‘element_based’)
security_limits	list, NULL	Security limit options
token_reduction	list, NULL	Token reduction options
use_cache	logical, NULL	Enable extraction result caching
Other options		Additional configuration parameters

Returns:

• Named list with configuration options

Example:

R

config <- extraction_config(
  ocr = ocr_config(backend = "tesseract", language = "eng"),
  chunking = chunking_config(max_characters = 1000L, overlap = 200L),
  use_cache = TRUE
)

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

---

From_file()

Load configuration from a TOML, YAML, or JSON file.

Signature:

R

from_file(path) -> list

Parameters:

Parameter	Type	Description
path	character	Path to configuration file (TOML, YAML, or JSON)

Returns:

• Named list with configuration

Example:

R

config <- from_file("kreuzberg.toml")
result <- extract_file_sync("document.pdf", config = config)

---

Layout_detection_config()

Create a layout detection configuration.

Signature:

R

layout_detection_config(confidence_threshold = NULL, apply_heuristics = TRUE, table_model = NULL, ...) -> list

Parameters:

Parameter	Type	Description
apply_heuristics	logical	Whether to apply heuristic post-processing to refine layout regions. Default: TRUE
confidence_threshold	numeric, NULL	Minimum confidence threshold for detected regions (0.0-1.0). Default: NULL
table_model	character, NULL	Table structure recognition model: “tatr” (default), “slanet_wired”, “slanet_wireless”, “slanet_plus”, “slanet_auto”. Default: NULL
…		Additional layout detection options

Returns:

• Named list with layout detection configuration

Example:

R

config <- extraction_config(
  layout = layout_detection_config(apply_heuristics = TRUE)
)

---

Ocr_config()

Create OCR configuration.

Signature:

R

ocr_config(backend = "tesseract", language = "eng", dpi = NULL, ...) -> list

Parameters:

Parameter	Type	Description
backend	character	OCR backend (“tesseract” or “paddle-ocr”). Default: “tesseract”
dpi	integer, NULL	DPI for OCR processing
language	character	Language code (ISO 639-3). Default: “eng”
model_tier	character, NULL	v4.5.0 PaddleOCR model tier: “mobile” (lightweight, ~21MB total, fast) or “server” (high accuracy, ~172MB, best with GPU). Default: “mobile”
padding	integer, NULL	v4.5.0 Padding in pixels (0-100) added around the image before PaddleOCR detection. Default: 10
…		Additional OCR options

Returns:

• Named list with OCR configuration

Example:

R

config <- extraction_config(
  ocr = ocr_config(backend = "paddle-ocr", language = "eng")
)

---

Results & Types

Kreuzberg_result

Result object returned by all extraction functions. Inherits from list with named fields.

Fields:

Field	Type	Description
annotations	list, NULL	PDF annotations (links, highlights, notes)
chunks	list, NULL	Text chunks (if chunking enabled)
content	character	Extracted text content
detected_language	character, NULL	Detected language code (ISO 639-1)
djot_content	list, NULL	Structured Djot content
document	list, NULL	Hierarchical document structure
elements	list, NULL	Document semantic elements
extracted_keywords	list, NULL	Extracted keywords with scores
images	list, NULL	Extracted images
metadata	list	Document metadata
mime_type	character	MIME type of the processed document
ocr_elements	list, NULL	OCR elements with positioning and confidence
pages	list, NULL	Per-page extracted content (if page extraction enabled)
processing_warnings	list, NULL	Non-fatal processing warnings
quality_score	numeric, NULL	Quality score (0.0-1.0)
tables	list, NULL	Array of extracted tables

Example:

R

result <- extract_file_sync("document.pdf")

cat("Content:", result$content, "\n")
cat("MIME type:", result$mime_type, "\n")
cat("Pages:", page_count(result), "\n")
cat("Tables:", length(result$tables), "\n")
cat("Language:", detected_language(result), "\n")

---

S3 Methods for kreuzberg_result

Chunk_count()

Get the number of text chunks.

R

chunk_count(x) -> integer

Example:

R

result <- extract_file_sync("document.pdf", config = extraction_config(chunking = chunking_config()))
chunks <- chunk_count(result)

---

Content()

Extract the text content.

R

content(x) -> character

Example:

R

result <- extract_file_sync("document.pdf")
text <- content(result)

---

Detected_language()

Get the detected language code.

R

detected_language(x) -> character or NULL

Example:

R

result <- extract_file_sync("document.pdf")
lang <- detected_language(result)
if (!is.null(lang)) {
  cat("Language:", lang, "\n")
}

---

Format()

Format the result as a string.

R

format(x)

---

Metadata_field()

Extract a specific metadata field by name.

R

metadata_field(x, name) -> value or NULL

Parameters:

Parameter	Type	Description
x	kreuzberg_result	Result object
name	character	Field name

Returns:

• Field value or NULL if not present

Example:

R

result <- extract_file_sync("document.pdf")
title <- metadata_field(result, "title")
author <- metadata_field(result, "author")

---

Mime_type()

Get the MIME type of the document.

R

mime_type(x) -> character

Example:

R

result <- extract_file_sync("document.pdf")
type <- mime_type(result)

---

Page_count()

Get the number of pages in the document.

R

page_count(x) -> integer

Example:

R

result <- extract_file_sync("document.pdf")
pages <- page_count(result)

---

Print()

Print a brief summary of the result.

R

print(x)

Example:

R

result <- extract_file_sync("document.pdf")
print(result)  # Displays summary

---

Summary()

Summarize the extraction result.

R

summary(object)

Example:

R

result <- extract_file_sync("document.pdf")
summary(result)

---

Metadata Hash

Document metadata with format-specific fields.

Common Fields:

Field	Type	Description
authors	character	Document authors
created_at	character	Creation date (ISO 8601)
created_by	character	Creator/application name
custom	list	Additional custom metadata from postprocessors
date	character	Document date (ISO 8601 format)
format_type	character	Format discriminator (“pdf”, “excel”, “email”, etc.)
keywords	character	Document keywords
language	character	Document language (ISO 639-1 code)
modified_at	character	Modification date (ISO 8601)
page_count	integer	Number of pages
producer	character	Producer/generator
subject	character	Document subject
title	character	Document title

Example:

R

result <- extract_file_sync("document.pdf")
metadata <- result$metadata

if (metadata$format_type == "pdf") {
  cat("Title:", metadata$title, "\n")
  cat("Author:", metadata$authors, "\n")
  cat("Pages:", metadata$page_count, "\n")
}

---

PDF Rendering

Added in v4.6.2

Render_pdf_page()

Render a single page of a PDF as a PNG image.

Signature:

R

render_pdf_page(path, page_index, dpi = 150L)

Parameters:

• path (character): Path to the PDF file
• page_index (integer): Zero-based page index to render
• dpi (integer): Resolution for rendering (default 150L)

Returns:

• raw vector: PNG-encoded raw vector for the requested page

Example:

render_single_page.R

png <- render_pdf_page("document.pdf", 0L)
writeBin(png, "first_page.png")

---

Error Handling

Errors are raised as typed conditions with class hierarchy:

• kreuzberg_error (base)
  • ValidationError
  • ParsingError
  • FileNotFoundError
  • UnsupportedFormatError
  • ExtractionError

Example - Basic error handling:

R

library(kreuzberg)

tryCatch(
  result <- extract_file_sync("document.pdf"),
  FileNotFoundError = function(e) {
    cat("File not found:", conditionMessage(e), "\n")
  },
  ValidationError = function(e) {
    cat("Validation error:", conditionMessage(e), "\n")
  },
  kreuzberg_error = function(e) {
    cat("Extraction error:", conditionMessage(e), "\n")
  }
)

Example - Specific error handling:

R

tryCatch(
  {
    result <- extract_file_sync("scanned.pdf", config = extraction_config(
      ocr = ocr_config(backend = "unsupported-backend")
    ))
  },
  ValidationError = function(e) {
    cat("Invalid configuration:", conditionMessage(e), "\n")
  },
  error = function(e) {
    cat("Unexpected error:", conditionMessage(e), "\n")
  }
)

---

Cache Management

Cache_stats()

Get cache statistics.

Signature:

R

cache_stats() -> list

Returns:

• Named list with:
  • total_entries (integer): Number of cached entries
  • total_size_bytes (integer): Total cache size in bytes

Example:

R

library(kreuzberg)

stats <- cache_stats()
cat("Cache entries:", stats$total_entries, "\n")
cat("Cache size:", stats$total_size_bytes, "bytes\n")

---

Clear_cache()

Clear the extraction cache.

Signature:

R

clear_cache() -> invisible(NULL)

Example:

R

library(kreuzberg)

clear_cache()

---

Validation

Validate_language_code()

Validate language code.

Signature:

R

validate_language_code(code) -> logical

Parameters:

Parameter	Type	Description
code	character	Language code (ISO 639-3 or 639-1)

Returns:

• Logical: TRUE if valid, FALSE otherwise

Example:

R

library(kreuzberg)

is_valid <- validate_language_code("eng")

---

Validate_mime_type()

Validate MIME type.

Signature:

R

validate_mime_type(mime_type) -> logical

Parameters:

Parameter	Type	Description
mime_type	character	MIME type to validate

Returns:

• Logical: TRUE if valid, FALSE otherwise

Example:

R

library(kreuzberg)

is_valid <- validate_mime_type("application/pdf")

---

Validate_ocr_backend_name()

Validate OCR backend name.

Signature:

R

validate_ocr_backend_name(backend) -> logical

Parameters:

Parameter	Type	Description
backend	character	Backend name to validate

Returns:

• Logical: TRUE if valid, FALSE otherwise

Example:

R

library(kreuzberg)

is_valid <- validate_ocr_backend_name("tesseract")
if (!is_valid) {
  cat("Invalid OCR backend\n")
}

---

Validate_output_format()

Validate output format.

Signature:

R

validate_output_format(format) -> logical

Parameters:

Parameter	Type	Description
format	character	Output format name

Returns:

• Logical: TRUE if valid, FALSE otherwise

---

Metadata Detection

Detect_mime_type()

Detect MIME type from raw bytes.

Signature:

R

detect_mime_type(data) -> character

Parameters:

Parameter	Type	Description
data	raw	Binary data

Returns:

• Character: Detected MIME type

Example:

R

library(kreuzberg)

data <- readBin("document", what = "raw", n = file.size("document"))
mime_type <- detect_mime_type(data)
cat("Detected MIME type:", mime_type, "\n")

---

Detect_mime_type_from_path()

Detect MIME type from file path.

Signature:

R

detect_mime_type_from_path(path) -> character

Parameters:

Parameter	Type	Description
path	character	File path

Returns:

• Character: Detected MIME type

Example:

R

library(kreuzberg)

mime_type <- detect_mime_type_from_path("document.pdf")
cat("MIME type:", mime_type, "\n")

---

Get_extensions_for_mime()

Get file extensions for a MIME type.

Signature:

R

get_extensions_for_mime(mime_type) -> character

Parameters:

Parameter	Type	Description
mime_type	character	MIME type

Returns:

• Character vector: File extensions for the MIME type

Example:

R

library(kreuzberg)

extensions <- get_extensions_for_mime("application/pdf")
cat("PDF extensions:", paste(extensions, collapse = ", "), "\n")

---

Plugins

OCR Backends

Clear_ocr_backends()

Clear all registered OCR backends.

Signature:

R

clear_ocr_backends() -> invisible(NULL)

---

List_ocr_backends()

List all registered OCR backends.

Signature:

R

list_ocr_backends() -> character

Returns:

• Character vector: Names of registered backends

Example:

R

library(kreuzberg)

backends <- list_ocr_backends()
cat("Available OCR backends:", paste(backends, collapse = ", "), "\n")

---

Register_ocr_backend()

Register a custom OCR backend.

Signature:

R

register_ocr_backend(name, callback) -> invisible(NULL)

Parameters:

Parameter	Type	Description
name	character	Backend name
callback	function	Backend implementation function

---

Unregister_ocr_backend()

Unregister an OCR backend.

Signature:

R

unregister_ocr_backend(name) -> invisible(NULL)

---

Post-Processors

Clear_post_processors()

Clear all registered post-processors.

Signature:

R

clear_post_processors() -> invisible(NULL)

---

List_post_processors()

List all registered post-processors.

Signature:

R

list_post_processors() -> character

Returns:

• Character vector: Names of registered post-processors

---

Register_post_processor()

Register a custom post-processor.

Signature:

R

register_post_processor(name, callback) -> invisible(NULL)

Parameters:

Parameter	Type	Description
name	character	Processor name
callback	function	Processor implementation function

---

Unregister_post_processor()

Unregister a post-processor.

Signature:

R

unregister_post_processor(name) -> invisible(NULL)

---

Validators

Clear_validators()

Clear all registered validators.

Signature:

R

clear_validators() -> invisible(NULL)

---

List_validators()

List all registered validators.

Signature:

R

list_validators() -> character

Returns:

• Character vector: Names of registered validators

---

Register_validator()

Register a custom validator.

Signature:

R

register_validator(name, callback) -> invisible(NULL)

Parameters:

Parameter	Type	Description
name	character	Validator name
callback	function	Validator implementation function

---

Unregister_validator()

Unregister a validator.

Signature:

R

unregister_validator(name) -> invisible(NULL)

---

Document Extractors

Clear_document_extractors()

Clear all document extractors.

Signature:

R

clear_document_extractors() -> invisible(NULL)

---

List_document_extractors()

List all available document extractors.

Signature:

R

list_document_extractors() -> character

Returns:

• Character vector: Names of available document extractors

---

Unregister_document_extractor()

Unregister a document extractor.

Signature:

R

unregister_document_extractor(name) -> invisible(NULL)

Parameters:

Parameter	Type	Description
name	character	Extractor name

---

Thread Safety

All Kreuzberg functions are thread-safe and can be called from multiple threads concurrently via R’s parallel package or future framework.

Example - Using parallel package:

R

library(kreuzberg)
library(parallel)

files <- c("doc1.pdf", "doc2.pdf", "doc3.pdf")

# Use parallel processing
results <- mclapply(files, function(file) {
  extract_file_sync(file)
}, mc.cores = 3)

for (i in seq_along(results)) {
  cat(sprintf("%s: %d characters\n", files[i], nchar(results[[i]]$content)))
}

Example - Using future package:

R

library(kreuzberg)
library(future)

plan(multisession)

files <- c("doc1.pdf", "doc2.pdf", "doc3.pdf")

# Process files asynchronously
futures <- lapply(files, function(file) {
  future({
    extract_file_sync(file)
  })
})

# Collect results
results <- lapply(futures, value)

for (i in seq_along(results)) {
  cat(sprintf("%s: %d characters\n", files[i], nchar(results[[i]]$content)))
}

However, for better performance, use the batch API instead:

R

library(kreuzberg)

files <- c("doc1.pdf", "doc2.pdf", "doc3.pdf")

# Better approach: use built-in batch processing
results <- batch_extract_files_sync(files)

for (i in seq_along(results)) {
  cat(sprintf("%s: %d characters\n", files[i], nchar(results[[i]]$content)))
}

---

LLM Integration

Kreuzberg integrates with LLMs via the liter-llm crate for structured extraction and VLM-based OCR. The R binding passes LLM configuration as list options through the extendr FFI layer. See the LLM Integration Guide for full details.

Structured Extraction

Pass structured_extraction config to extract structured data from documents using an LLM:

structured_extraction.R

library(kreuzberg)

config <- list(
  structured_extraction = list(
    schema = list(
      type = "object",
      properties = list(
        title = list(type = "string"),
        authors = list(type = "array", items = list(type = "string")),
        date = list(type = "string")
      ),
      required = c("title", "authors", "date"),
      additionalProperties = FALSE
    ),
    llm = list(model = "openai/gpt-4o-mini"),
    strict = TRUE
  )
)

result <- extract_file_sync("paper.pdf", config = config)

if (!is.null(result$structured_output)) {
  data <- jsonlite::fromJSON(result$structured_output)
  cat("Title:", data$title, "\n")
}

VLM OCR

Use a vision-language model as an OCR backend:

vlm_ocr.R

config <- list(
  force_ocr = TRUE,
  ocr = list(
    backend = "vlm",
    vlm_config = list(model = "openai/gpt-4o-mini")
  )
)

result <- extract_file_sync("scan.pdf", config = config)

For configuration details including API keys, model selection, and provider setup, see the LLM Integration Guide.