PHP API Reference

PHP API Reference v5.0.0-rc.3¶

Functions¶

extractBytes()¶

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:

public static function extractBytes(string $content, string $mimeType, ExtractionConfig $config): ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Throws Error.

extractFile()¶

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:

public static function extractFile(string $path, ?string $mimeType = null, ExtractionConfig $config): ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Throws Error.

extractFileSync()¶

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:

public static function extractFileSync(string $path, ?string $mimeType = null, ExtractionConfig $config): ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Throws Error.

extractBytesSync()¶

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:

public static function extractBytesSync(string $content, string $mimeType, ExtractionConfig $config): ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Throws Error.

batchExtractFilesSync()¶

Synchronous wrapper for batch_extract_files.

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

Signature:

public static function batchExtractFilesSync(array<BatchFileItem> $items, ExtractionConfig $config): array<ExtractionResult>

Parameters:

Returns: array<ExtractionResult> Errors: Throws Error.

batchExtractBytesSync()¶

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:

public static function batchExtractBytesSync(array<BatchBytesItem> $items, ExtractionConfig $config): array<ExtractionResult>

Parameters:

Returns: array<ExtractionResult> Errors: Throws Error.

batchExtractFiles()¶

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:

public static function batchExtractFiles(array<BatchFileItem> $items, ExtractionConfig $config): array<ExtractionResult>

Parameters:

Returns: array<ExtractionResult> Errors: Throws Error.

batchExtractBytes()¶

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:

public static function batchExtractBytes(array<BatchBytesItem> $items, ExtractionConfig $config): array<ExtractionResult>

Parameters:

Returns: array<ExtractionResult> Errors: Throws Error.

detectMimeTypeFromBytes()¶

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:

public static function detectMimeTypeFromBytes(string $content): string

Parameters:

Returns: string Errors: Throws Error.

getExtensionsForMime()¶

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:

public static function getExtensionsForMime(string $mimeType): array<string>

Parameters:

Returns: array<string> Errors: Throws Error.

clearEmbeddingBackends()¶

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:

public static function clearEmbeddingBackends(): void

Returns: void Errors: Throws Error.

listEmbeddingBackends()¶

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:

public static function listEmbeddingBackends(): array<string>

Returns: array<string> Errors: Throws Error.

listDocumentExtractors()¶

List names of all registered document extractors.

Signature:

public static function listDocumentExtractors(): array<string>

Returns: array<string> Errors: Throws Error.

clearDocumentExtractors()¶

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:

public static function clearDocumentExtractors(): void

Returns: void Errors: Throws Error.

listOcrBackends()¶

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:

public static function listOcrBackends(): array<string>

Returns: array<string> Errors: Throws Error.

clearOcrBackends()¶

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:

public static function clearOcrBackends(): void

Returns: void Errors: Throws Error.

listPostProcessors()¶

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:

public static function listPostProcessors(): array<string>

Returns: array<string> Errors: Throws Error.

clearPostProcessors()¶

Remove all registered post-processors.

Signature:

public static function clearPostProcessors(): void

Returns: void Errors: Throws Error.

listRenderers()¶

List names of all registered renderers.

Errors:

Returns an error if the registry lock is poisoned.

Signature:

public static function listRenderers(): array<string>

Returns: array<string> Errors: Throws Error.

clearRenderers()¶

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:

public static function clearRenderers(): void

Returns: void Errors: Throws Error.

listValidators()¶

List names of all registered validators.

Signature:

public static function listValidators(): array<string>

Returns: array<string> Errors: Throws Error.

clearValidators()¶

Remove all registered validators.

Signature:

public static function clearValidators(): void

Returns: void Errors: Throws Error.

embedTextsAsync()¶

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:

public static function embedTextsAsync(array<string> $texts, EmbeddingConfig $config): array<array<float>>

Parameters:

Returns: array<array<float>> Errors: Throws Error.

renderPdfPageToPng()¶

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:

public static function renderPdfPageToPng(string $pdfBytes, int $pageIndex, ?int $dpi = null, ?string $password = null): string

Parameters:

Returns: string Errors: Throws Error.

detectMimeType()¶

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:

public static function detectMimeType(string $path, bool $checkExists): string

Parameters:

Returns: string Errors: Throws Error.

embedTexts()¶

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:

public static function embedTexts(array<string> $texts, EmbeddingConfig $config): array<array<float>>

Parameters:

Returns: array<array<float>> Errors: Throws Error.

getEmbeddingPreset()¶

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:

public static function getEmbeddingPreset(string $name): ?EmbeddingPreset

Parameters:

Returns: ?EmbeddingPreset

listEmbeddingPresets()¶

List the names of all available embedding presets.

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

Signature:

public static function listEmbeddingPresets(): array<string>

Returns: array<string>

Types¶

AccelerationConfig¶

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.

ArchiveEntry¶

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.

ArchiveMetadata¶

Archive (ZIP/TAR/7Z) metadata.

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

BBox¶

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

BatchBytesItem¶

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.

BatchFileItem¶

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.

BibtexMetadata¶

BibTeX bibliography metadata.

BoundingBox¶

Bounding box coordinates for element positioning.

Chunk¶

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.

ChunkMetadata¶

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

ChunkingConfig¶

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¶

default()¶

Signature:

public static function default(): ChunkingConfig

CitationMetadata¶

Citation file metadata (RIS, PubMed, EndNote).

ContentFilterConfig¶

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¶

default()¶

Signature:

public static function default(): ContentFilterConfig

ContributorRole¶

JATS contributor with role.

CoreProperties¶

Dublin Core metadata from docProps/core.xml

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

CsvMetadata¶

CSV/TSV file metadata.

DbfFieldInfo¶

dBASE field information.

DbfMetadata¶

dBASE (DBF) file metadata.

DetectResponse¶

MIME type detection response.

DetectionResult¶

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

DjotContent¶

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.

DjotImage¶

Image element in Djot.

DjotLink¶

Link element in Djot.

DocumentExtractor¶

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¶

extractBytes()¶

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:

public function extractBytes(string $content, string $mimeType, ExtractionConfig $config): InternalDocument

extractFile()¶

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:

public function extractFile(string $path, string $mimeType, ExtractionConfig $config): InternalDocument

supportedMimeTypes()¶

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:

public function supportedMimeTypes(): array<string>

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:

public function priority(): int

canHandle()¶

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:

public function canHandle(string $path, string $mimeType): bool

asSyncExtractor()¶

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:

public function asSyncExtractor(): ?SyncExtractor

DocumentNode¶

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.

DocumentRelationship¶

A resolved relationship between two nodes in the document tree.

DocumentStructure¶

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¶

finalizeNodeTypes()¶

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:

public function finalizeNodeTypes(): void

isEmpty()¶

Check if the document structure is empty.

Signature:

public function isEmpty(): bool

default()¶

Signature:

public static function default(): DocumentStructure

DocxAppProperties¶

Application properties from docProps/app.xml for DOCX

Contains Word-specific document statistics and metadata.

DocxMetadata¶

Word document metadata.

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

Element¶

Semantic element extracted from document.

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

ElementMetadata¶

Metadata for a semantic element.

EmailAttachment¶

Email attachment representation.

Contains metadata and optionally the content of an email attachment.

EmailConfig¶

Configuration for email extraction.

EmailExtractionResult¶

Email extraction result.

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

EmailMetadata¶

Email metadata extracted from .eml and .msg files.

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

EmbeddedFile¶

Embedded file descriptor extracted from the PDF name tree.

EmbeddingBackend¶

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¶

dimensions()¶

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

Signature:

public function dimensions(): int

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:

public function embed(array<string> $texts): array<array<float>>

EmbeddingConfig¶

Embedding configuration for text chunks.

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

Methods¶

default()¶

Signature:

public static function default(): EmbeddingConfig

EmbeddingPreset¶

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.

EpubMetadata¶

EPUB metadata (Dublin Core extensions).

ErrorMetadata¶

Error metadata (for batch operations).

ExcelMetadata¶

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.

ExcelSheet¶

Single Excel worksheet.

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

ExcelWorkbook¶

Excel workbook representation.

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

ExtractedImage¶

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.

ExtractedImageMetadata¶

Image metadata extracted from an image file.

ExtractionConfig¶

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¶

default()¶

Signature:

public static function default(): ExtractionConfig

needsImageProcessing()¶

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:

public function needsImageProcessing(): bool

ExtractionResult¶

General extraction result used by the core extraction API.

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

Methods¶

fromOcr()¶

Convert from an OCR result.

Signature:

public static function fromOcr(OcrExtractionResult $ocr): ExtractionResult

FictionBookMetadata¶

FictionBook (FB2) metadata.

FileExtractionConfig¶

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

Footnote¶

Footnote in Djot.

FormattedBlock¶

Block-level element in a Djot document.

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

GridCell¶

Individual grid cell with position and span metadata.

HeaderMetadata¶

Header/heading element metadata.

HeadingContext¶

Heading context for a chunk within a Markdown document.

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

HeadingLevel¶

A single heading in the hierarchy.

HierarchicalBlock¶

A text block with hierarchy level assignment.

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

HierarchyConfig¶

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¶

default()¶

Signature:

public static function default(): HierarchyConfig

HtmlMetadata¶

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).

HtmlOutputConfig¶

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¶

default()¶

Signature:

public static function default(): HtmlOutputConfig

ImageExtractionConfig¶

Image extraction configuration.

Methods¶

default()¶

Signature:

public static function default(): ImageExtractionConfig

ImageMetadata¶

Image metadata extracted from image files.

Includes dimensions, format, and EXIF data.

ImageMetadataType¶

Image element metadata.

ImagePreprocessingConfig¶

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¶

default()¶

Signature:

public static function default(): ImagePreprocessingConfig

ImagePreprocessingMetadata¶

Image preprocessing metadata.

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

InlineElement¶

Inline element within a block.

Represents text with formatting, links, images, etc.

JatsMetadata¶

JATS (Journal Article Tag Suite) metadata.

Keyword¶

Extracted keyword with metadata.

KeywordConfig¶

Keyword extraction configuration.

Methods¶

default()¶

Signature:

public static function default(): KeywordConfig

LanguageDetectionConfig¶

Language detection configuration.

Methods¶

default()¶

Signature:

public static function default(): LanguageDetectionConfig

LayoutDetection¶

A single layout detection result.

LayoutDetectionConfig¶

Layout detection configuration.

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

Methods¶

default()¶

Signature:

public static function default(): LayoutDetectionConfig

LayoutRegion¶

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.

LinkMetadata¶

Link element metadata.

LlmConfig¶

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.

LlmUsage¶

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).

Metadata¶

Extraction result metadata.

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

Methods¶

isEmpty()¶

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

Signature:

public function isEmpty(): bool

ModelPaths¶

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

OcrBackend¶

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¶

processImage()¶

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:

public function processImage(string $imageBytes, OcrConfig $config): ExtractionResult

processImageFile()¶

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:

public function processImageFile(string $path, OcrConfig $config): ExtractionResult

supportsLanguage()¶

Check if this backend supports a given language code.

Returns:

true if the language is supported, false otherwise.

Signature:

public function supportsLanguage(string $lang): bool

backendType()¶

Get the backend type identifier.

Returns:

The backend type enum value.

Signature:

public function backendType(): OcrBackendType

supportedLanguages()¶

Optional: Get a list of all supported languages.

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

Signature:

public function supportedLanguages(): array<string>

supportsTableDetection()¶

Optional: Check if the backend supports table detection.

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

Signature:

public function supportsTableDetection(): bool

supportsDocumentProcessing()¶

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:

public function supportsDocumentProcessing(): bool

processDocument()¶

Process a document file directly via OCR.

Only called if supports_document_processing returns true.

Signature:

public function processDocument(string $path, OcrConfig $config): ExtractionResult

OcrCacheStats¶

OcrConfidence¶

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).

OcrConfig¶

OCR configuration.

Methods¶

default()¶

Signature:

public static function default(): OcrConfig

OcrElement¶

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.

OcrElementConfig¶

Configuration for OCR element extraction.

Controls how OCR elements are extracted and filtered.

OcrExtractionResult¶

OCR extraction result.

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

OcrMetadata¶

OCR processing metadata.

Captures information about OCR processing configuration and results.

OcrPipelineConfig¶

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.

OcrPipelineStage¶

A single backend stage in the OCR pipeline.

OcrQualityThresholds¶

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¶

default()¶

Signature:

public static function default(): OcrQualityThresholds

OcrRotation¶

Rotation information for an OCR element.

OcrTable¶

Table detected via OCR.

Represents a table structure recognized during OCR processing.

OcrTableBoundingBox¶

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

OrientationResult¶

Document orientation detection result.

PaddleOcrConfig¶

Configuration for PaddleOCR backend.

Configures PaddleOCR text detection and recognition with multi-language support. Uses a builder pattern for convenient configuration.

Methods¶

withCacheDir()¶

Sets a custom cache directory for model files.

Signature:

public function withCacheDir(string $path): PaddleOcrConfig

withTableDetection()¶

Enables or disables table structure detection.

Signature:

public function withTableDetection(bool $enable): PaddleOcrConfig

withAngleCls()¶

Enables or disables angle classification for rotated text.

Signature:

public function withAngleCls(bool $enable): PaddleOcrConfig

withDetDbThresh()¶

Sets the database threshold for text detection.

Signature:

public function withDetDbThresh(float $threshold): PaddleOcrConfig

withDetDbBoxThresh()¶

Sets the box threshold for text bounding box refinement.

Signature:

public function withDetDbBoxThresh(float $threshold): PaddleOcrConfig

withDetDbUnclipRatio()¶

Sets the unclip ratio for expanding text bounding boxes.

Signature:

public function withDetDbUnclipRatio(float $ratio): PaddleOcrConfig

withDetLimitSideLen()¶

Sets the maximum side length for detection images.

Signature:

public function withDetLimitSideLen(int $length): PaddleOcrConfig

withRecBatchNum()¶

Sets the batch size for recognition inference.

Signature:

public function withRecBatchNum(int $batchSize): PaddleOcrConfig

withDropScore()¶

Sets the minimum recognition confidence threshold.

Signature:

public function withDropScore(float $score): PaddleOcrConfig

withPadding()¶

Sets padding in pixels added around images before detection.

Signature:

public function withPadding(int $padding): PaddleOcrConfig

withModelTier()¶

Sets the model tier controlling detection/recognition model size.

Signature:

public function withModelTier(string $tier): PaddleOcrConfig

default()¶

Creates a default configuration with English language support.

Signature:

public static function default(): PaddleOcrConfig

PageBoundary¶

Byte offset boundary for a page.

Tracks where a specific page's content starts and ends in the main content string, enabling mapping from byte positions to page numbers. Offsets are guaranteed to be at valid UTF-8 character boundaries when using standard String methods (push_str, push, etc.).

PageConfig¶

Page extraction and tracking configuration.

Controls how pages are extracted, tracked, and represented in the extraction results. When null, page tracking is disabled.

Page range tracking in chunk metadata (first_page/last_page) is automatically enabled when page boundaries are available and chunking is configured.

"` | Page marker format (use {page_num} placeholder) Default: "\n\n\n\n" |

Methods¶

default()¶

Signature:

public static function default(): PageConfig

PageContent¶

Content for a single page/slide.

When page extraction is enabled, documents are split into per-page content with associated tables and images mapped to each page.

Performance¶

Uses Arc-wrapped tables and images for memory efficiency:

• Vec<Arc<Table>> enables zero-copy sharing of table data
• Vec<Arc<ExtractedImage>> enables zero-copy sharing of image data
• Maintains exact JSON compatibility via custom Serialize/Deserialize

This reduces memory overhead for documents with shared tables/images by avoiding redundant copies during serialization.