Python API Reference

Python API Reference v5.0.0-rc.3¶

Functions¶

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:

def extract_bytes(content: bytes, mime_type: str, config: ExtractionConfig) -> ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Raises Error.

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:

def extract_file(path: str, mime_type: str = None, config: ExtractionConfig) -> ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Raises Error.

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:

def extract_file_sync(path: str, mime_type: str = None, config: ExtractionConfig) -> ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Raises Error.

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:

def extract_bytes_sync(content: bytes, mime_type: str, config: ExtractionConfig) -> ExtractionResult

Parameters:

Returns: ExtractionResult Errors: Raises Error.

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:

def batch_extract_files_sync(items: list[BatchFileItem], config: ExtractionConfig) -> list[ExtractionResult]

Parameters:

Returns: list[ExtractionResult] Errors: Raises Error.

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:

def batch_extract_bytes_sync(items: list[BatchBytesItem], config: ExtractionConfig) -> list[ExtractionResult]

Parameters:

Returns: list[ExtractionResult] Errors: Raises Error.

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 None 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:

def batch_extract_files(items: list[BatchFileItem], config: ExtractionConfig) -> list[ExtractionResult]

Parameters:

Returns: list[ExtractionResult] Errors: Raises Error.

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 None 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:

def batch_extract_bytes(items: list[BatchBytesItem], config: ExtractionConfig) -> list[ExtractionResult]

Parameters:

Returns: list[ExtractionResult] Errors: Raises Error.

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:

def detect_mime_type_from_bytes(content: bytes) -> str

Parameters:

Returns: str Errors: Raises Error.

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:

def get_extensions_for_mime(mime_type: str) -> list[str]

Parameters:

Returns: list[str] Errors: Raises Error.

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:

def clear_embedding_backends() -> None

Returns: None Errors: Raises Error.

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:

def list_embedding_backends() -> list[str]

Returns: list[str] Errors: Raises Error.

list_document_extractors()¶

List names of all registered document extractors.

Signature:

def list_document_extractors() -> list[str]

Returns: list[str] Errors: Raises Error.

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:

def clear_document_extractors() -> None

Returns: None Errors: Raises Error.

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:

def list_ocr_backends() -> list[str]

Returns: list[str] Errors: Raises Error.

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:

def clear_ocr_backends() -> None

Returns: None Errors: Raises Error.

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:

def list_post_processors() -> list[str]

Returns: list[str] Errors: Raises Error.

clear_post_processors()¶

Remove all registered post-processors.

Signature:

def clear_post_processors() -> None

Returns: None Errors: Raises Error.

list_renderers()¶

List names of all registered renderers.

Errors:

Returns an error if the registry lock is poisoned.

Signature:

def list_renderers() -> list[str]

Returns: list[str] Errors: Raises Error.

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:

def clear_renderers() -> None

Returns: None Errors: Raises Error.

list_validators()¶

List names of all registered validators.

Signature:

def list_validators() -> list[str]

Returns: list[str] Errors: Raises Error.

clear_validators()¶

Remove all registered validators.

Signature:

def clear_validators() -> None

Returns: None Errors: Raises Error.

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:

def embed_texts_async(texts: list[str], config: EmbeddingConfig) -> list[list[float]]

Parameters:

Returns: list[list[float]] Errors: Raises Error.

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:

def render_pdf_page_to_png(pdf_bytes: bytes, page_index: int, dpi: int = None, password: str = None) -> bytes

Parameters:

Returns: bytes Errors: Raises Error.

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:

def detect_mime_type(path: str, check_exists: bool) -> str

Parameters:

Returns: str Errors: Raises Error.

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:

def embed_texts(texts: list[str], config: EmbeddingConfig) -> list[list[float]]

Parameters:

Returns: list[list[float]] Errors: Raises Error.

get_embedding_preset()¶

Get an embedding preset by name.

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

Signature:

def get_embedding_preset(name: str) -> EmbeddingPreset | None

Parameters:

Returns: EmbeddingPreset | None

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:

def list_embedding_presets() -> list[str]

Returns: list[str]

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:

@staticmethod
def 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 None on ExtractionConfig, each extractor uses its current default behavior unchanged.

Methods¶

default()¶

Signature:

@staticmethod
def 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¶

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:

def extract_bytes(self, content: bytes, mime_type: str, config: ExtractionConfig) -> InternalDocument

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:

def extract_file(self, path: str, mime_type: str, config: ExtractionConfig) -> InternalDocument

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:

def supported_mime_types(self) -> list[str]

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:

def priority(self) -> int

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:

def can_handle(self, path: str, mime_type: str) -> bool

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:

def as_sync_extractor(self) -> SyncExtractor | None

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¶

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:

def finalize_node_types(self) -> None

is_empty()¶

Check if the document structure is empty.

Signature:

def is_empty(self) -> bool

default()¶

Signature:

@staticmethod
def 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:

def dimensions(self) -> 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:

def embed(self, texts: list[str]) -> list[list[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:

@staticmethod
def 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:

@staticmethod
def default() -> ExtractionConfig

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:

def needs_image_processing(self) -> bool

ExtractionResult¶

General extraction result used by the core extraction API.

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

Methods¶

from_ocr()¶

Convert from an OCR result.

Signature:

@staticmethod
def from_ocr(ocr: OcrExtractionResult) -> ExtractionResult

FictionBookMetadata¶

FictionBook (FB2) metadata.

FileExtractionConfig¶

Per-file extraction configuration overrides for batch processing.

All fields are Option<T> — None 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:

@staticmethod
def 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:

@staticmethod
def default() -> HtmlOutputConfig

ImageExtractionConfig¶

Image extraction configuration.

Methods¶

default()¶

Signature:

@staticmethod
def 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:

@staticmethod
def 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:

@staticmethod
def default() -> KeywordConfig

LanguageDetectionConfig¶

Language detection configuration.

Methods¶

default()¶

Signature:

@staticmethod
def 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:

@staticmethod
def 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¶

is_empty()¶

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

Signature:

def is_empty(self) -> 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¶

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:

def process_image(self, image_bytes: bytes, config: OcrConfig) -> ExtractionResult

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:

def process_image_file(self, path: str, config: OcrConfig) -> ExtractionResult

supports_language()¶

Check if this backend supports a given language code.

Returns:

True if the language is supported, False otherwise.

Signature:

def supports_language(self, lang: str) -> bool

backend_type()¶

Get the backend type identifier.

Returns:

The backend type enum value.

Signature:

def backend_type(self) -> OcrBackendType

supported_languages()¶

Optional: Get a list of all supported languages.

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

Signature:

def supported_languages(self) -> list[str]

supports_table_detection()¶

Optional: Check if the backend supports table detection.

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

Signature:

def supports_table_detection(self) -> bool

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:

def supports_document_processing(self) -> bool

process_document()¶

Process a document file directly via OCR.

Only called if supports_document_processing returns True.

Signature:

def process_document(self, path: str, config: OcrConfig) -> 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:

@staticmethod
def 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:

@staticmethod
def default() -> OcrQualityThresholds