C API Reference

C API Reference v5.0.0-rc.3¶

Functions¶

kreuzberg_extract_bytes()¶

Extract content from a byte array.

This is the main entry point for in-memory extraction. It performs the following steps:

1. Validate MIME type
2. Handle legacy format conversion if needed
3. Select appropriate extractor from registry
4. Extract content
5. Run post-processing pipeline

Returns:

An ExtractionResult containing the extracted content and metadata.

Errors:

Returns KreuzbergError.Validation if MIME type is invalid. Returns KreuzbergError.UnsupportedFormat if MIME type is not supported.

Signature:

KreuzbergExtractionResult* kreuzberg_extract_bytes(const uint8_t* content, const char* mime_type, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult Errors: Returns NULL on error.

kreuzberg_extract_file()¶

Extract content from a file.

This is the main entry point for file-based extraction. It performs the following steps:

1. Check cache for existing result (if caching enabled)
2. Detect or validate MIME type
3. Select appropriate extractor from registry
4. Extract content
5. Run post-processing pipeline
6. Store result in cache (if caching enabled)

Returns:

An ExtractionResult containing the extracted content and metadata.

Errors:

Returns KreuzbergError.Io if the file doesn't exist (NotFound) or for other file I/O errors. Returns KreuzbergError.UnsupportedFormat if MIME type is not supported.

Signature:

KreuzbergExtractionResult* kreuzberg_extract_file(const char* path, const char* mime_type, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult Errors: Returns NULL on error.

kreuzberg_extract_file_sync()¶

Synchronous wrapper for extract_file.

This is a convenience function that blocks the current thread until extraction completes. For async code, use extract_file directly.

Uses the global Tokio runtime for 100x+ performance improvement over creating a new runtime per call. Always uses the global runtime to avoid nested runtime issues.

This function is only available with the tokio-runtime feature. For WASM targets, use a truly synchronous extraction approach instead.

Signature:

KreuzbergExtractionResult* kreuzberg_extract_file_sync(const char* path, const char* mime_type, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult Errors: Returns NULL on error.

kreuzberg_extract_bytes_sync()¶

Synchronous wrapper for extract_bytes.

Uses the global Tokio runtime for 100x+ performance improvement over creating a new runtime per call.

With the tokio-runtime feature, this blocks the current thread using the global Tokio runtime. Without it (WASM), this calls a truly synchronous implementation.

Signature:

KreuzbergExtractionResult* kreuzberg_extract_bytes_sync(const uint8_t* content, const char* mime_type, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult Errors: Returns NULL on error.

kreuzberg_batch_extract_files_sync()¶

Synchronous wrapper for batch_extract_files.

Uses the global Tokio runtime for optimal performance. Only available with tokio-runtime (WASM has no filesystem).

Signature:

KreuzbergExtractionResult* kreuzberg_batch_extract_files_sync(KreuzbergBatchFileItem* items, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult* Errors: Returns NULL on error.

kreuzberg_batch_extract_bytes_sync()¶

Synchronous wrapper for batch_extract_bytes.

Uses the global Tokio runtime for optimal performance. With the tokio-runtime feature, this blocks the current thread using the global Tokio runtime. Without it (WASM), this calls a truly synchronous implementation that iterates through items and calls extract_bytes_sync().

Signature:

KreuzbergExtractionResult* kreuzberg_batch_extract_bytes_sync(KreuzbergBatchBytesItem* items, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult* Errors: Returns NULL on error.

kreuzberg_batch_extract_files()¶

Extract content from multiple files concurrently.

This function processes multiple files in parallel, automatically managing concurrency to prevent resource exhaustion. The concurrency limit can be configured via ExtractionConfig.max_concurrent_extractions or defaults to (num_cpus * 1.5).ceil().

Each file can optionally specify a FileExtractionConfig that overrides specific fields from the batch-level config. Pass NULL for a file to use the batch defaults. Batch-level settings like max_concurrent_extractions and use_cache are always taken from the batch-level config.

per-file configuration overrides.

• config - Batch-level extraction configuration (provides defaults and batch settings)

Returns:

A vector of ExtractionResult in the same order as the input items.

Errors:

Individual file errors are captured in the result metadata. System errors (IO, RuntimeError equivalents) will bubble up and fail the entire batch.

Simple usage with no per-file overrides:

Per-file configuration overrides:

Signature:

KreuzbergExtractionResult* kreuzberg_batch_extract_files(KreuzbergBatchFileItem* items, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult* Errors: Returns NULL on error.

kreuzberg_batch_extract_bytes()¶

Extract content from multiple byte arrays concurrently.

This function processes multiple byte arrays in parallel, automatically managing concurrency to prevent resource exhaustion. The concurrency limit can be configured via ExtractionConfig.max_concurrent_extractions or defaults to (num_cpus * 1.5).ceil().

Each item can optionally specify a FileExtractionConfig that overrides specific fields from the batch-level config. Pass NULL as the config to use the batch-level defaults for that item.

MIME type, and optional per-item configuration overrides.

• config - Batch-level extraction configuration

Returns:

A vector of ExtractionResult in the same order as the input items.

Simple usage with no per-item overrides:

Per-item configuration overrides:

Signature:

KreuzbergExtractionResult* kreuzberg_batch_extract_bytes(KreuzbergBatchBytesItem* items, KreuzbergExtractionConfig config);

Parameters:

Returns: KreuzbergExtractionResult* Errors: Returns NULL on error.

kreuzberg_detect_mime_type_from_bytes()¶

Detect MIME type from raw file bytes.

Uses magic byte signatures to detect file type from content. Falls back to infer crate for comprehensive detection.

For ZIP-based files, inspects contents to distinguish Office Open XML formats (DOCX, XLSX, PPTX) from plain ZIP archives.

Returns:

The detected MIME type string.

Errors:

Returns KreuzbergError.UnsupportedFormat if MIME type cannot be determined.

Signature:

const char* kreuzberg_detect_mime_type_from_bytes(const uint8_t* content);

Parameters:

Returns: const char* Errors: Returns NULL on error.

kreuzberg_get_extensions_for_mime()¶

Get file extensions for a given MIME type.

Returns all known file extensions that map to the specified MIME type.

Returns:

A vector of file extensions (without leading dot) for the MIME type.

Signature:

const char** kreuzberg_get_extensions_for_mime(const char* mime_type);

Parameters:

Returns: const char** Errors: Returns NULL on error.

kreuzberg_clear_embedding_backends()¶

Clear all embedding backends from the global registry.

Calls shutdown() on every registered backend, then empties the registry.

Errors:

• Any error returned by a backend's shutdown() method. The first error encountered stops processing of remaining backends.

Signature:

void kreuzberg_clear_embedding_backends();

Returns: void Errors: Returns NULL on error.

kreuzberg_list_embedding_backends()¶

List the names of all registered embedding backends.

Used by kreuzberg-cli and the api/mcp endpoints; excluded from the language bindings via alef.toml [exclude].functions.

Signature:

const char** kreuzberg_list_embedding_backends();

Returns: const char** Errors: Returns NULL on error.

kreuzberg_list_document_extractors()¶

List names of all registered document extractors.

Signature:

const char** kreuzberg_list_document_extractors();

Returns: const char** Errors: Returns NULL on error.

kreuzberg_clear_document_extractors()¶

Clear all document extractors from the global registry.

Calls shutdown() on every registered extractor, then empties the registry.

Errors:

• Any error returned by an extractor's shutdown() method. The first error encountered stops processing of remaining extractors.

Signature:

void kreuzberg_clear_document_extractors();

Returns: void Errors: Returns NULL on error.

kreuzberg_list_ocr_backends()¶

List all registered OCR backends.

Returns the names of all OCR backends currently registered in the global registry.

Returns:

A vector of OCR backend names.

Signature:

const char** kreuzberg_list_ocr_backends();

Returns: const char** Errors: Returns NULL on error.

kreuzberg_clear_ocr_backends()¶

Clear all OCR backends from the global registry.

Removes all OCR backends and calls their shutdown() methods.

Returns:

• Ok(()) if all backends were cleared successfully
• Err(...) if any shutdown method failed

Signature:

void kreuzberg_clear_ocr_backends();

Returns: void Errors: Returns NULL on error.

kreuzberg_list_post_processors()¶

List all registered post-processor names.

Returns a vector of all post-processor names currently registered in the global registry.

Returns:

• Ok(Vec<String>) - Vector of post-processor names
• Err(...) if the registry lock is poisoned

Signature:

const char** kreuzberg_list_post_processors();

Returns: const char** Errors: Returns NULL on error.

kreuzberg_clear_post_processors()¶

Remove all registered post-processors.

Signature:

void kreuzberg_clear_post_processors();

Returns: void Errors: Returns NULL on error.

kreuzberg_list_renderers()¶

List names of all registered renderers.

Errors:

Returns an error if the registry lock is poisoned.

Signature:

const char** kreuzberg_list_renderers();

Returns: const char** Errors: Returns NULL on error.

kreuzberg_clear_renderers()¶

Clear all renderers from the global registry.

Removes every renderer, including the built-in defaults (markdown, html, djot, plain). After calling this no renderers are registered; re-register as needed.

Errors:

Returns an error if the registry lock is poisoned.

Signature:

void kreuzberg_clear_renderers();

Returns: void Errors: Returns NULL on error.

kreuzberg_list_validators()¶

List names of all registered validators.

Signature:

const char** kreuzberg_list_validators();

Returns: const char** Errors: Returns NULL on error.

kreuzberg_clear_validators()¶

Remove all registered validators.

Signature:

void kreuzberg_clear_validators();

Returns: void Errors: Returns NULL on error.

kreuzberg_embed_texts_async()¶

Generate embeddings asynchronously for a list of text strings.

This is the async counterpart to embed_texts. It offloads the blocking ONNX inference work to a dedicated blocking thread pool via Tokio's spawn_blocking, keeping the async executor free.

Returns one embedding vector per input text in the same order.

Errors:

• KreuzbergError.MissingDependency if ONNX Runtime is not installed
• KreuzbergError.Embedding if the preset name is unknown, model download fails, or the blocking inference task panics

Signature:

float** kreuzberg_embed_texts_async(const char** texts, KreuzbergEmbeddingConfig config);

Parameters:

Returns: float** Errors: Returns NULL on error.

kreuzberg_render_pdf_page_to_png()¶

Render a single PDF page to PNG bytes.

Returns raw PNG-encoded bytes for the specified page at the given DPI. Uses pdf_oxide with tiny-skia for pure-Rust rendering.

Errors:

Returns KreuzbergError.Parsing if the PDF cannot be opened, authenticated, or rendered, or if page_index is out of range.

Signature:

const uint8_t* kreuzberg_render_pdf_page_to_png(const uint8_t* pdf_bytes, uintptr_t page_index, int32_t dpi, const char* password);

Parameters:

Returns: const uint8_t* Errors: Returns NULL on error.

kreuzberg_detect_mime_type()¶

Detect the MIME type of a file at the given path.

Uses the file extension and optionally the file content to determine the MIME type. Set check_exists to true to verify the file exists before detection.

Signature:

const char* kreuzberg_detect_mime_type(const char* path, bool check_exists);

Parameters:

Returns: const char* Errors: Returns NULL on error.

kreuzberg_embed_texts()¶

Embed a list of texts using the configured embedding model.

Returns a 2D vector where each inner vector is the embedding for the corresponding text.

Signature:

float** kreuzberg_embed_texts(const char** texts, KreuzbergEmbeddingConfig config);

Parameters:

Returns: float** Errors: Returns NULL on error.

kreuzberg_get_embedding_preset()¶

Get an embedding preset by name.

Returns NULL if no preset with the given name exists. Returns an owned clone so the value is safe to pass across FFI boundaries.

Signature:

KreuzbergEmbeddingPreset* kreuzberg_get_embedding_preset(const char* name);

Parameters:

Returns: KreuzbergEmbeddingPreset*

kreuzberg_list_embedding_presets()¶

List the names of all available embedding presets.

Returns owned Strings so the values are safe to pass across FFI boundaries.

Signature:

const char** kreuzberg_list_embedding_presets();

Returns: const char**

Types¶

KreuzbergAccelerationConfig¶

Hardware acceleration configuration for ONNX Runtime models.

Controls which execution provider (CPU, CoreML, CUDA, TensorRT) is used for inference in layout detection and embedding generation.

KreuzbergArchiveEntry¶

A single file extracted from an archive.

When archives (ZIP, TAR, 7Z, GZIP) are extracted with recursive extraction enabled, each processable file produces its own full ExtractionResult.

KreuzbergArchiveMetadata¶

Archive (ZIP/TAR/7Z) metadata.

Extracted from compressed archive files containing file lists and size information.

KreuzbergBBox¶

Bounding box in original image coordinates (x1, y1) top-left, (x2, y2) bottom-right.

KreuzbergBatchBytesItem¶

Batch item for byte array extraction.

Used with batch_extract_bytes and batch_extract_bytes_sync to represent a single item in a batch extraction job.

KreuzbergBatchFileItem¶

Batch item for file extraction.

Used with batch_extract_files and batch_extract_files_sync to represent a single file in a batch extraction job.

KreuzbergBibtexMetadata¶

BibTeX bibliography metadata.

KreuzbergBoundingBox¶

Bounding box coordinates for element positioning.

KreuzbergChunk¶

A text chunk with optional embedding and metadata.

Chunks are created when chunking is enabled in ExtractionConfig. Each chunk contains the text content, optional embedding vector (if embedding generation is configured), and metadata about its position in the document.

KreuzbergChunkMetadata¶

Metadata about a chunk's position in the original document.

KreuzbergChunkingConfig¶

Chunking configuration.

Configures text chunking for document content, including chunk size, overlap, trimming behavior, and optional embeddings.

Use ..the default constructor when constructing to allow for future field additions:

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergChunkingConfig kreuzberg_default();

KreuzbergCitationMetadata¶

Citation file metadata (RIS, PubMed, EndNote).

KreuzbergContentFilterConfig¶

Cross-extractor content filtering configuration.

Controls whether "furniture" content (headers, footers, page numbers, watermarks, repeating text) is included in or stripped from extraction results. Applies across all extractors (PDF, DOCX, RTF, ODT, HTML, etc.) with format-specific implementation.

When NULL on ExtractionConfig, each extractor uses its current default behavior unchanged.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergContentFilterConfig kreuzberg_default();

KreuzbergContributorRole¶

JATS contributor with role.

KreuzbergCoreProperties¶

Dublin Core metadata from docProps/core.xml

Contains standard metadata fields defined by the Dublin Core standard and Office-specific extensions.

KreuzbergCsvMetadata¶

CSV/TSV file metadata.

KreuzbergDbfFieldInfo¶

dBASE field information.

KreuzbergDbfMetadata¶

dBASE (DBF) file metadata.

KreuzbergDetectResponse¶

MIME type detection response.

KreuzbergDetectionResult¶

Page-level detection result containing all detections and page metadata.

KreuzbergDjotContent¶

Comprehensive Djot document structure with semantic preservation.

This type captures the full richness of Djot markup, including:

• Block-level structures (headings, lists, blockquotes, code blocks, etc.)
• Inline formatting (emphasis, strong, highlight, subscript, superscript, etc.)
• Attributes (classes, IDs, key-value pairs)
• Links, images, footnotes
• Math expressions (inline and display)
• Tables with full structure

Available when the djot feature is enabled.

KreuzbergDjotImage¶

Image element in Djot.

KreuzbergDjotLink¶

Link element in Djot.

KreuzbergDocumentExtractor¶

Trait for document extractor plugins.

Implement this trait to add support for new document formats or to override built-in extraction behavior with custom logic.

Return Type¶

Extractors return InternalDocument, a flat intermediate representation. The pipeline converts this into the public ExtractionResult via the derivation step.

Priority System¶

When multiple extractors support the same MIME type, the registry selects the extractor with the highest priority value. Use this to:

• Override built-in extractors (priority > 50)
• Provide fallback extractors (priority < 50)
• Implement specialized extractors for specific use cases

Default priority is 50.

Thread Safety¶

Extractors must be thread-safe (Send + Sync) to support concurrent extraction.

Methods¶

kreuzberg_extract_bytes()¶

Extract content from a byte array.

This is the core extraction method that processes in-memory document data.

Returns:

An InternalDocument containing the extracted elements, metadata, and tables. The pipeline will convert this into the public ExtractionResult.

Errors:

• KreuzbergError.Parsing - Document parsing failed
• KreuzbergError.Validation - Invalid document structure
• KreuzbergError.Io - I/O errors (these always bubble up)
• KreuzbergError.MissingDependency - Required dependency not available

Signature:

KreuzbergInternalDocument kreuzberg_extract_bytes(const uint8_t* content, const char* mime_type, KreuzbergExtractionConfig config);

kreuzberg_extract_file()¶

Extract content from a file.

Default implementation reads the file and calls extract_bytes. Override for custom file handling, streaming, or memory optimizations.

Returns:

An InternalDocument containing the extracted elements, metadata, and tables.

Errors:

Same as extract_bytes, plus file I/O errors.

Signature:

KreuzbergInternalDocument kreuzberg_extract_file(const char* path, const char* mime_type, KreuzbergExtractionConfig config);

kreuzberg_supported_mime_types()¶

Get the list of MIME types supported by this extractor.

Can include exact MIME types and prefix patterns:

• Exact: "application/pdf", "text/plain"
• Prefix: "image/*" (matches any image type)

Returns:

A slice of MIME type strings.

Signature:

const char** kreuzberg_supported_mime_types();

kreuzberg_priority()¶

Get the priority of this extractor.

Higher priority extractors are preferred when multiple extractors support the same MIME type.

Priority Guidelines¶

• 0-25: Fallback/low-quality extractors
• 26-49: Alternative extractors
• 50: Default priority (built-in extractors)
• 51-75: Premium/enhanced extractors
• 76-100: Specialized/high-priority extractors

Returns:

Priority value (default: 50)

Signature:

int32_t kreuzberg_priority();

kreuzberg_can_handle()¶

Optional: Check if this extractor can handle a specific file.

Allows for more sophisticated detection beyond MIME types. Defaults to true (rely on MIME type matching).

Returns:

true if the extractor can handle this file, false otherwise.

Signature:

bool kreuzberg_can_handle(const char* path, const char* mime_type);

kreuzberg_as_sync_extractor()¶

Attempt to get a reference to this extractor as a SyncExtractor.

Returns None if the extractor doesn't support synchronous extraction. This is used for WASM and other sync-only environments.

Signature:

KreuzbergSyncExtractor* kreuzberg_as_sync_extractor();

KreuzbergDocumentNode¶

A single node in the document tree.

Each node has deterministic id, typed content, optional parent/children for tree structure, and metadata like page number, bounding box, and content layer.

KreuzbergDocumentRelationship¶

A resolved relationship between two nodes in the document tree.

KreuzbergDocumentStructure¶

Top-level structured document representation.

A flat array of nodes with index-based parent/child references forming a tree. Root-level nodes have parent: None. Use body_roots() and furniture_roots() to iterate over top-level content by layer.

Validation¶

Call validate() after construction to verify all node indices are in bounds and parent-child relationships are bidirectionally consistent.

Methods¶

kreuzberg_finalize_node_types()¶

Compute and populate the node_types field from the current nodes.

Call this after all nodes have been added to the structure. Internal construction paths (builder, derivation) call this automatically.

Signature:

void kreuzberg_finalize_node_types();

kreuzberg_is_empty()¶

Check if the document structure is empty.

Signature:

bool kreuzberg_is_empty();

kreuzberg_default()¶

Signature:

KreuzbergDocumentStructure kreuzberg_default();

KreuzbergDocxAppProperties¶

Application properties from docProps/app.xml for DOCX

Contains Word-specific document statistics and metadata.

KreuzbergDocxMetadata¶

Word document metadata.

Extracted from DOCX files using shared Office Open XML metadata extraction. Integrates with office_metadata module for core/app/custom properties.

KreuzbergElement¶

Semantic element extracted from document.

Represents a logical unit of content with semantic classification, unique identifier, and metadata for tracking origin and position.

KreuzbergElementMetadata¶

Metadata for a semantic element.

KreuzbergEmailAttachment¶

Email attachment representation.

Contains metadata and optionally the content of an email attachment.

KreuzbergEmailConfig¶

Configuration for email extraction.

KreuzbergEmailExtractionResult¶

Email extraction result.

Complete representation of an extracted email message (.eml or .msg) including headers, body content, and attachments.

KreuzbergEmailMetadata¶

Email metadata extracted from .eml and .msg files.

Includes sender/recipient information, message ID, and attachment list.

KreuzbergEmbeddedFile¶

Embedded file descriptor extracted from the PDF name tree.

KreuzbergEmbeddingBackend¶

Trait for in-process embedding backend plugins.

Async to match the convention used by OcrBackend, DocumentExtractor, and PostProcessor. Host-language bridges (PyO3, napi-rs, Rustler, extendr, magnus, ext-php-rs, C FFI, etc.) wrap their synchronous host callables in spawn_blocking or the equivalent to satisfy the async signature.

Thread safety¶

Backends must be Send + Sync + 'static. They are stored in Arc<dyn EmbeddingBackend> and called concurrently from kreuzberg's chunking pipeline. If the backend's underlying model isn't thread-safe, the backend itself must serialize access internally (e.g. via Mutex<Inner>).

Contract¶

• embed(texts) MUST return exactly texts.len() vectors, each of length self.dimensions(). The dispatcher in embed_texts validates this before returning to downstream consumers; a non-conforming backend surfaces as a KreuzbergError.Validation, not a panic.

• embed may be called from any thread. Its future must be Send (enforced by async_trait when #[async_trait] is used on non-WASM targets).

• dimensions() is called exactly once at registration, immediately after initialize() succeeds. The returned value is cached by the registry and used for all subsequent shape validation. Lazy-loading implementations can defer model loading into initialize() and report the real dimension afterwards. Later mutations of the backend's reported dimension are not observed by kreuzberg — implementations that need to change dimension must unregister and re-register.

• shutdown() (inherited from Plugin) may be invoked concurrently with an in-flight embed() call. Implementations must tolerate this — e.g. by letting in-flight calls finish using resources held via the Arc<dyn EmbeddingBackend> reference, and only releasing shared state that isn't needed by embed.

Runtime¶

The synchronous embed_texts entry uses tokio.task.block_in_place to await the trait's async embed, which requires a multi-thread tokio runtime. Callers running inside a current_thread runtime (e.g. #[tokio.test] without flavor = "multi_thread", or tokio.runtime.Builder.new_current_thread()) must use embed_texts_async instead, which awaits directly without block_in_place.

Methods¶

kreuzberg_dimensions()¶

Embedding vector dimension. Must be > 0 and must match the length of every vector returned by embed.

Signature:

uintptr_t kreuzberg_dimensions();

kreuzberg_embed()¶

Embed a batch of texts, returning one vector per input in order.

Errors:

Implementations should return Plugin for backend-specific failures. The dispatcher layers its own validation (length, per-vector dimension) on top.

Signature:

float** kreuzberg_embed(const char** texts);

KreuzbergEmbeddingConfig¶

Embedding configuration for text chunks.

Configures embedding generation using ONNX models via the vendored embedding engine. Requires the embeddings feature to be enabled.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergEmbeddingConfig kreuzberg_default();

KreuzbergEmbeddingPreset¶

Preset configurations for common RAG use cases.

Each preset combines chunk size, overlap, and embedding model to provide an optimized configuration for specific scenarios.

All string fields are owned String for FFI compatibility — instances are safe to clone and pass across language boundaries.

KreuzbergEpubMetadata¶

EPUB metadata (Dublin Core extensions).

KreuzbergErrorMetadata¶

Error metadata (for batch operations).

KreuzbergExcelMetadata¶

Excel/spreadsheet format metadata.

Identifies the document as a spreadsheet source via the FormatMetadata.Excel discriminant. Sheet count and sheet names are stored inside this struct.

KreuzbergExcelSheet¶

Single Excel worksheet.

Represents one sheet from an Excel workbook with its content converted to Markdown format and dimensional statistics.

KreuzbergExcelWorkbook¶

Excel workbook representation.

Contains all sheets from an Excel file (.xlsx, .xls, etc.) with extracted content and metadata.

KreuzbergExtractedImage¶

Extracted image from a document.

Contains raw image data, metadata, and optional nested OCR results. Raw bytes allow cross-language compatibility - users can convert to PIL.Image (Python), Sharp (Node.js), or other formats as needed.

KreuzbergExtractedImageMetadata¶

Image metadata extracted from an image file.

KreuzbergExtractionConfig¶

Main extraction configuration.

This struct contains all configuration options for the extraction process. It can be loaded from TOML, YAML, or JSON files, or created programmatically.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergExtractionConfig kreuzberg_default();

kreuzberg_needs_image_processing()¶

Check if image processing is needed by examining OCR and image extraction settings.

Returns true if either OCR is enabled or image extraction is configured, indicating that image decompression and processing should occur. Returns false if both are disabled, allowing optimization to skip unnecessary image decompression for text-only extraction workflows.

Optimization Impact¶

For text-only extractions (no OCR, no image extraction), skipping image decompression can improve CPU utilization by 5-10% by avoiding wasteful image I/O and processing when results won't be used.

Signature:

bool kreuzberg_needs_image_processing();

KreuzbergExtractionResult¶

General extraction result used by the core extraction API.

This is the main result type returned by all extraction functions.

Methods¶

kreuzberg_from_ocr()¶

Convert from an OCR result.

Signature:

KreuzbergExtractionResult kreuzberg_from_ocr(KreuzbergOcrExtractionResult ocr);

KreuzbergFictionBookMetadata¶

FictionBook (FB2) metadata.

KreuzbergFileExtractionConfig¶

Per-file extraction configuration overrides for batch processing.

All fields are Option<T> — NULL means "use the batch-level default." This type is used with batch_extract_files and batch_extract_bytes to allow heterogeneous extraction settings within a single batch.

Excluded Fields¶

The following ExtractionConfig fields are batch-level only and cannot be overridden per file:

• max_concurrent_extractions — controls batch parallelism
• use_cache — global caching policy
• acceleration — shared ONNX execution provider
• security_limits — global archive security policy

KreuzbergFootnote¶

Footnote in Djot.

KreuzbergFormattedBlock¶

Block-level element in a Djot document.

Represents structural elements like headings, paragraphs, lists, code blocks, etc.

KreuzbergGridCell¶

Individual grid cell with position and span metadata.

KreuzbergHeaderMetadata¶

Header/heading element metadata.

KreuzbergHeadingContext¶

Heading context for a chunk within a Markdown document.

Contains the heading hierarchy from document root to this chunk's section.

KreuzbergHeadingLevel¶

A single heading in the hierarchy.

KreuzbergHierarchicalBlock¶

A text block with hierarchy level assignment.

Represents a block of text with semantic heading information extracted from font size clustering and hierarchical analysis.

KreuzbergHierarchyConfig¶

Hierarchy extraction configuration for PDF text structure analysis.

Enables extraction of document hierarchy levels (H1-H6) based on font size clustering and semantic analysis. When enabled, hierarchical blocks are included in page content.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergHierarchyConfig kreuzberg_default();

KreuzbergHtmlMetadata¶

HTML metadata extracted from HTML documents.

Includes document-level metadata, Open Graph data, Twitter Card metadata, and extracted structural elements (headers, links, images, structured data).

KreuzbergHtmlOutputConfig¶

Configuration for styled HTML output.

When set on ExtractionConfig.html_output alongside output_format = OutputFormat.Html, the pipeline builds a StyledHtmlRenderer instead of the plain comrak-based renderer.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergHtmlOutputConfig kreuzberg_default();

KreuzbergImageExtractionConfig¶

Image extraction configuration.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergImageExtractionConfig kreuzberg_default();

KreuzbergImageMetadata¶

Image metadata extracted from image files.

Includes dimensions, format, and EXIF data.

KreuzbergImageMetadataType¶

Image element metadata.

KreuzbergImagePreprocessingConfig¶

Image preprocessing configuration for OCR.

These settings control how images are preprocessed before OCR to improve text recognition quality. Different preprocessing strategies work better for different document types.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergImagePreprocessingConfig kreuzberg_default();

KreuzbergImagePreprocessingMetadata¶

Image preprocessing metadata.

Tracks the transformations applied to an image during OCR preprocessing, including DPI normalization, resizing, and resampling.

KreuzbergInlineElement¶

Inline element within a block.

Represents text with formatting, links, images, etc.

KreuzbergJatsMetadata¶

JATS (Journal Article Tag Suite) metadata.

KreuzbergKeyword¶

Extracted keyword with metadata.

KreuzbergKeywordConfig¶

Keyword extraction configuration.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergKeywordConfig kreuzberg_default();

KreuzbergLanguageDetectionConfig¶

Language detection configuration.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergLanguageDetectionConfig kreuzberg_default();

KreuzbergLayoutDetection¶

A single layout detection result.

KreuzbergLayoutDetectionConfig¶

Layout detection configuration.

Controls layout detection behavior in the extraction pipeline. When set on ExtractionConfig, layout detection is enabled for PDF extraction.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergLayoutDetectionConfig kreuzberg_default();

KreuzbergLayoutRegion¶

A detected layout region on a page.

When layout detection is enabled, each page may have layout regions identifying different content types (text, pictures, tables, etc.) with confidence scores and spatial positions.

KreuzbergLinkMetadata¶

Link element metadata.

KreuzbergLlmConfig¶

Configuration for an LLM provider/model via liter-llm.

Each feature (VLM OCR, VLM embeddings, structured extraction) carries its own LlmConfig, allowing different providers per feature.

KreuzbergLlmUsage¶

Token usage and cost data for a single LLM call made during extraction.

Populated when VLM OCR, structured extraction, or LLM-based embeddings are used. Multiple entries may be present when multiple LLM calls occur within one extraction (e.g. VLM OCR + structured extraction).

KreuzbergMetadata¶

Extraction result metadata.

Contains common fields applicable to all formats, format-specific metadata via a discriminated union, and additional custom fields from postprocessors.

Methods¶

kreuzberg_is_empty()¶

Returns true when no metadata fields, format-specific metadata, or additional postprocessor fields are populated.

Signature:

bool kreuzberg_is_empty();

KreuzbergModelPaths¶

Combined paths to all models needed for OCR (backward compatibility).

KreuzbergOcrBackend¶

Trait for OCR backend plugins.

Implement this trait to add custom OCR capabilities. OCR backends can be:

• Native Rust implementations (like Tesseract)
• FFI bridges to Python libraries (like EasyOCR, PaddleOCR)
• Cloud-based OCR services (Google Vision, AWS Textract, etc.)

Thread Safety¶

OCR backends must be thread-safe (Send + Sync) to support concurrent processing.

Methods¶

kreuzberg_process_image()¶

Process an image and extract text via OCR.

Returns:

An ExtractionResult containing the extracted text and metadata.

Errors:

• KreuzbergError.Ocr - OCR processing failed
• KreuzbergError.Validation - Invalid image format or configuration
• KreuzbergError.Io - I/O errors (these always bubble up)

Reading backend_options¶

Backends that support runtime tuning can read config.backend_options and deserialize only the keys they care about. Unknown keys are silently ignored, so multiple backends can coexist in a pipeline without key conflicts.

Signature:

KreuzbergExtractionResult kreuzberg_process_image(const uint8_t* image_bytes, KreuzbergOcrConfig config);

kreuzberg_process_image_file()¶

Process a file and extract text via OCR.

Default implementation reads the file and calls process_image. Override for custom file handling or optimizations.

Errors:

Same as process_image, plus file I/O errors.

Signature:

KreuzbergExtractionResult kreuzberg_process_image_file(const char* path, KreuzbergOcrConfig config);

kreuzberg_supports_language()¶

Check if this backend supports a given language code.

Returns:

true if the language is supported, false otherwise.

Signature:

bool kreuzberg_supports_language(const char* lang);

kreuzberg_backend_type()¶

Get the backend type identifier.

Returns:

The backend type enum value.

Signature:

KreuzbergOcrBackendType kreuzberg_backend_type();

kreuzberg_supported_languages()¶

Optional: Get a list of all supported languages.

Defaults to empty list. Override to provide comprehensive language support info.

Signature:

const char** kreuzberg_supported_languages();

kreuzberg_supports_table_detection()¶

Optional: Check if the backend supports table detection.

Defaults to false. Override if your backend can detect and extract tables.

Signature:

bool kreuzberg_supports_table_detection();

kreuzberg_supports_document_processing()¶

Check if the backend supports direct document-level processing (e.g. for PDFs).

Defaults to false. Override if the backend has optimized document processing.

Signature:

bool kreuzberg_supports_document_processing();

kreuzberg_process_document()¶

Process a document file directly via OCR.

Only called if supports_document_processing returns true.

Signature:

KreuzbergExtractionResult kreuzberg_process_document(const char* path, KreuzbergOcrConfig config);

KreuzbergOcrCacheStats¶

KreuzbergOcrConfidence¶

Confidence scores for an OCR element.

Separates detection confidence (how confident that text exists at this location) from recognition confidence (how confident about the actual text content).

KreuzbergOcrConfig¶

OCR configuration.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergOcrConfig kreuzberg_default();

KreuzbergOcrElement¶

A unified OCR element representing detected text with full metadata.

This is the primary type for structured OCR output, preserving all information from both Tesseract and PaddleOCR backends.

KreuzbergOcrElementConfig¶

Configuration for OCR element extraction.

Controls how OCR elements are extracted and filtered.

KreuzbergOcrExtractionResult¶

OCR extraction result.

Result of performing OCR on an image or scanned document, including recognized text and detected tables.

KreuzbergOcrMetadata¶

OCR processing metadata.

Captures information about OCR processing configuration and results.

KreuzbergOcrPipelineConfig¶

Multi-backend OCR pipeline with quality-based fallback.

Backends are tried in priority order (highest first). After each backend produces output, quality is evaluated. If it meets quality_thresholds.pipeline_min_quality, the result is accepted. Otherwise the next backend is tried.

KreuzbergOcrPipelineStage¶

A single backend stage in the OCR pipeline.

KreuzbergOcrQualityThresholds¶

Quality thresholds for OCR fallback decisions and pipeline quality gating.

All fields default to the values that match the previous hardcoded behavior, so OcrQualityThresholds.default() preserves existing semantics exactly.

Methods¶

kreuzberg_default()¶

Signature:

KreuzbergOcrQualityThresholds kreuzberg_default();

KreuzbergOcrRotation¶

Rotation information for an OCR element.

KreuzbergOcrTable¶

Table detected via OCR.

Represents a table structure recognized during OCR processing.

KreuzbergOcrTableBoundingBox¶

Bounding box for an OCR-detected table in pixel coordinates.

KreuzbergOrientationResult¶

Document orientation detection result.