Zig API Reference

Zig API Reference v5.0.0-rc.30¶

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:

pub fn extract_bytes(content: []const u8, mime_type: [:0]const u8, config: ExtractionConfig) Error!ExtractionResult

Example:

const result = try extractBytes("data", "value", .{});

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:

pub fn extract_file(path: [:0]const u8, mime_type: ?[:0]const u8, config: ExtractionConfig) Error!ExtractionResult

Example:

const result = try extractFile("value", "value", .{});

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:

pub fn extract_file_sync(path: [:0]const u8, mime_type: ?[:0]const u8, config: ExtractionConfig) Error!ExtractionResult

Example:

const result = try extractFileSync("value", "value", .{});

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:

pub fn extract_bytes_sync(content: []const u8, mime_type: [:0]const u8, config: ExtractionConfig) Error!ExtractionResult

Example:

const result = try extractBytesSync("data", "value", .{});

Parameters:

Returns: ExtractionResult

Errors: Throws Error.

extractBytesSync()¶

Synchronous wrapper for extract_bytes (WASM-compatible version).

This is a truly synchronous implementation without tokio runtime dependency. It calls extract_bytes_sync_impl() to perform the extraction.

Signature:

pub fn extract_bytes_sync(content: []const u8, mime_type: [:0]const u8, config: ExtractionConfig) Error!ExtractionResult

Example:

const result = try extractBytesSync("data", "value", .{});

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:

pub fn batch_extract_files_sync(items: []const BatchFileItem, config: ExtractionConfig) Error![]const ExtractionResult

Example:

const result = try batchExtractFilesSync(&[_]u8{}, .{});

Parameters:

Returns: []const 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:

pub fn batch_extract_bytes_sync(items: []const BatchBytesItem, config: ExtractionConfig) Error![]const ExtractionResult

Example:

const result = try batchExtractBytesSync(&[_]u8{}, .{});

Parameters:

Returns: []const ExtractionResult

Errors: Throws Error.

batchExtractBytesSync()¶

Synchronous wrapper for batch_extract_bytes (WASM-compatible version).

Iterates through items sequentially, applying per-file config overrides.

Signature:

pub fn batch_extract_bytes_sync(items: []const BatchBytesItem, config: ExtractionConfig) Error![]const ExtractionResult

Example:

const result = try batchExtractBytesSync(&[_]u8{}, .{});

Parameters:

Returns: []const 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:

pub fn batch_extract_files(items: []const BatchFileItem, config: ExtractionConfig) Error![]const ExtractionResult

Example:

const result = try batchExtractFiles(&[_]u8{}, .{});

Parameters:

Returns: []const 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:

pub fn batch_extract_bytes(items: []const BatchBytesItem, config: ExtractionConfig) Error![]const ExtractionResult

Example:

const result = try batchExtractBytes(&[_]u8{}, .{});

Parameters:

Returns: []const 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:

pub fn detect_mime_type_from_bytes(content: []const u8) Error![:0]const u8

Example:

const result = try detectMimeTypeFromBytes("data");

Parameters:

Returns: [:0]const u8

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:

pub fn get_extensions_for_mime(mime_type: [:0]const u8) Error![]const [:0]const u8

Example:

const result = try getExtensionsForMime("value");

Parameters:

Returns: []const [:0]const u8

Errors: Throws Error.

listSupportedFormats()¶

List all supported document formats.

Returns every file extension Kreuzberg recognizes together with its corresponding MIME type, derived from the central format registry. Formats that have no registered file extension (such as source code, which is detected dynamically) are not included.

The list is sorted alphabetically by file extension.

Returns:

A vector of SupportedFormat entries sorted by extension.

Signature:

pub fn list_supported_formats() []const SupportedFormat

Example:

const result = listSupportedFormats();

Returns: []const SupportedFormat

detectQrCodes()¶

Detect QR codes in the bytes of an ExtractedImage.

format_hint is currently unused — the image crate auto-detects the container format from magic bytes — but the parameter is retained so future backends (e.g. a WebP-via-webp-decoder variant) can use it without an API break.

Returns an empty listtor on any of:

• Empty input.
• Image-decode failure.
• No QR grids detected.
• All detected grids fail to decode.

Successfully decoded QR codes carry their payload, a confidence of 1.0 (rqrr does not expose per-grid confidence; a successful decode is treated as high-confidence by convention), and the pixel-space bounding box derived from the four corner points of the grid.

Signature:

pub fn detect_qr_codes(image_bytes: []const u8, format_hint: ?[:0]const u8) []const QrCode

Example:

const result = detectQrCodes("data", "value");

Parameters:

Returns: []const QrCode

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:

pub fn clear_embedding_backends() Error!void

Example:

try clearEmbeddingBackends();

Returns: No return value.

Errors: Throws Error.

listEmbeddingBackends()¶

List the names of all registered embedding backends.

Used by kreuzberg-cli, the api/mcp endpoints, and generated language bindings.

Signature:

pub fn list_embedding_backends() Error![]const [:0]const u8

Example:

const result = try listEmbeddingBackends();

Returns: []const [:0]const u8

Errors: Throws Error.

listDocumentExtractors()¶

List names of all registered document extractors.

Signature:

pub fn list_document_extractors() Error![]const [:0]const u8

Example:

const result = try listDocumentExtractors();

Returns: []const [:0]const u8

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:

pub fn clear_document_extractors() Error!void

Example:

try clearDocumentExtractors();

Returns: No return value.

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:

pub fn list_ocr_backends() Error![]const [:0]const u8

Example:

const result = try listOcrBackends();

Returns: []const [:0]const u8

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:

pub fn clear_ocr_backends() Error!void

Example:

try clearOcrBackends();

Returns: No return value.

Errors: Throws Error.

registerBuiltin()¶

Register every built-in post-processor enabled by the active feature set.

This is the single entry point that callers (including register_default_post_processors) use to populate the global post-processor registry with the in-tree built-ins. Each submodule's own register function is gated by its feature flag so this aggregate stays safe to call on any target.

Signature:

pub fn register_builtin() Error!void

Example:

try registerBuiltin();

Returns: No return value.

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([]const []const u8) - Vector of post-processor names
• Err(...) if the registry lock is poisoned

Signature:

pub fn list_post_processors() Error![]const [:0]const u8

Example:

const result = try listPostProcessors();

Returns: []const [:0]const u8

Errors: Throws Error.

clearPostProcessors()¶

Remove all registered post-processors.

Signature:

pub fn clear_post_processors() Error!void

Example:

try clearPostProcessors();

Returns: No return value.

Errors: Throws Error.

listRenderers()¶

List names of all registered renderers.

Errors:

Returns an error if the registry lock is poisoned.

Signature:

pub fn list_renderers() Error![]const [:0]const u8

Example:

const result = try listRenderers();

Returns: []const [:0]const u8

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:

pub fn clear_renderers() Error!void

Example:

try clearRenderers();

Returns: No return value.

Errors: Throws Error.

clearRerankerBackends()¶

Clear all reranker 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.

Since v5.0.

Signature:

pub fn clear_reranker_backends() Error!void

Example:

try clearRerankerBackends();

Returns: No return value.

Errors: Throws Error.

listRerankerBackends()¶

List the names of all registered reranker backends.

Used by kreuzberg-cli, the api/mcp endpoints, and generated language bindings.

Since v5.0.

Signature:

pub fn list_reranker_backends() Error![]const [:0]const u8

Example:

const result = try listRerankerBackends();

Returns: []const [:0]const u8

Errors: Throws Error.

listValidators()¶

List names of all registered validators.

Signature:

pub fn list_validators() Error![]const [:0]const u8

Example:

const result = try listValidators();

Returns: []const [:0]const u8

Errors: Throws Error.

clearValidators()¶

Remove all registered validators.

Signature:

pub fn clear_validators() Error!void

Example:

try clearValidators();

Returns: No return value.

Errors: Throws Error.

classifyPages()¶

Run page classification against an extraction result.

Mutates result.page_classifications with one entry per non-empty page and appends every LLM call's usage to result.llm_usage.

Errors:

Returns the first error encountered when rendering the prompt or calling the LLM. Partially produced classifications are discarded so callers do not see a half-populated vector.

Signature:

pub fn classify_pages(result: ExtractionResult, config: PageClassificationConfig) Error!void

Example:

try classifyPages(.{}, .{});

Parameters:

Returns: No return value.

Errors: Throws Error.

classifyText()¶

Classify a single piece of text without requiring an ExtractionResult.

Use this when the caller already has plain text (e.g. a RAG ingest pipeline receiving documents off a queue) and wants a label list back without manufacturing extractor-side metadata.

Errors:

Same as classify_pages: a validation error when config.labels is empty, or any error returned by prompt rendering or the underlying LLM call.

Signature:

pub fn classify_text(text: [:0]const u8, config: PageClassificationConfig) Error![]const ClassificationLabel

Example:

const result = try classifyText("value", .{});

Parameters:

Returns: []const ClassificationLabel

Errors: Throws Error.

classifyDocument()¶

Classify a single document (as multiple pages or a single text block).

Aggregates classifications across all pages in the provided text, returning a combined label set that represents the document as a whole.

using the configured LLM, and results are aggregated.

• config - Classification configuration including labels and LLM settings.

Returns:

A vector of ClassificationLabel entries representing the document's overall classification.

Errors:

Returns an error if config.labels is empty or if LLM calls fail.

Signature:

pub fn classify_document(pages: []const [:0]const u8, config: PageClassificationConfig) Error![]const ClassificationLabel

Example:

const result = try classifyDocument(&[_]u8{}, .{});

Parameters:

Returns: []const ClassificationLabel

Errors: Throws Error.

downloadModel()¶

Eagerly download a NER model into the kreuzberg cache.

name is a HuggingFace repo id (e.g. urchade/gliner_multi-v2.1). The CLI flag kreuzberg warm --ner delegates here.

Signature:

pub fn download_model(name: [:0]const u8, cache_dir: ?[:0]const u8) Error![:0]const u8

Example:

const result = try downloadModel("value", "value");

Parameters:

Returns: [:0]const u8

Errors: Throws Error.

downloadModel()¶

Signature:

pub fn download_model(name: [:0]const u8, cache_dir: ?[:0]const u8) Error![:0]const u8

Example:

const result = try downloadModel("value", "value");

Parameters:

Returns: [:0]const u8

Errors: Throws Error.

defaultModelName()¶

Pinned default NER model identifier.

Signature:

pub fn default_model_name() [:0]const u8

Example:

const result = defaultModelName();

Returns: [:0]const u8

defaultModelName()¶

Signature:

pub fn default_model_name() [:0]const u8

Example:

const result = defaultModelName();

Returns: [:0]const u8

knownModels()¶

All NER models kreuzberg knows about (used by --all-ner-models).

Signature:

pub fn known_models() []const [:0]const u8

Example:

const result = knownModels();

Returns: []const [:0]const u8

knownModels()¶

Signature:

pub fn known_models() []const [:0]const u8

Example:

const result = knownModels();

Returns: []const [:0]const u8

downloadModel()¶

Download a NER model into the kreuzberg cache.

Signature:

pub fn download_model(name: [:0]const u8, cache_dir: ?[:0]const u8) Error![:0]const u8

Example:

const result = try downloadModel("value", "value");

Parameters:

Returns: [:0]const u8

Errors: Throws Error.

defaultModelName()¶

Default NER model identifier.

Signature:

pub fn default_model_name() [:0]const u8

Example:

const result = defaultModelName();

Returns: [:0]const u8

knownModels()¶

All NER models kreuzberg knows about.

Signature:

pub fn known_models() []const [:0]const u8

Example:

const result = knownModels();

Returns: []const [:0]const u8

redact()¶

Run pattern redaction (and optional NER-driven redaction) over result and rewrite every textual field. Populates result.redaction_report.

Signature:

pub fn redact(result: ExtractionResult, config: RedactionConfig) Error!void

Example:

try redact(.{}, .{});

Parameters:

Returns: No return value.

Errors: Throws Error.

findAll()¶

Find all US Social Security Number spans in text (format: NNN-NN-NNNN).

Signature:

pub fn find_all(text: [:0]const u8) []const PatternMatch

Example:

const result = findAll("value");

Parameters:

Returns: []const PatternMatch

scanText()¶

Scan text for every PII category in categories and return all matches in source-byte order.

When categories is empty every supported regex-detectable category fires. Person / Organization / Location are not covered by the pattern engine — they must be supplied by a NER backend through the redaction engine.

Signature:

pub fn scan_text(text: [:0]const u8, categories: []const PiiCategory) []const PatternMatch

Example:

const result = scanText("value", &[_]u8{});

Parameters:

Returns: []const PatternMatch

summarize()¶

Score and return the top-N sentences from text, joined in original order.

language is an ISO 639 (or locale) code used to pick a stopword list; pass null (or an unknown code) to fall back to English. max_tokens bounds the summary length by whitespace-separated tokens; null falls back to DEFAULT_MAX_TOKENS.

Signature:

pub fn summarize(text: [:0]const u8, language: ?[:0]const u8, max_tokens: ?u32) ?[:0]const u8

Example:

const result = summarize("value", "value", 42);

Parameters:

Returns: ?[:0]const u8

tokenCount()¶

Count whitespace-separated tokens (used for token-budget bookkeeping by callers).

Signature:

pub fn token_count(text: [:0]const u8) u32

Example:

const result = tokenCount("value");

Parameters:

Returns: u32

translateResult()¶

Translate the extraction result in place.

Populates result.translation with the translated content, optionally the translated formatted_content (when preserve_markup = true), and rewrites every chunk's content field. Every LLM call's usage is appended to result.llm_usage.

Signature:

pub fn translate_result(result: ExtractionResult, config: TranslationConfig) Error!void

Example:

try translateResult(.{}, .{});

Parameters:

Returns: No return value.

Errors: Throws Error.

findFootnoteAnchors()¶

Find all footnote anchor references in markdown text.

Returns a vector of footnote anchors ([^label] use-sites), including byte offsets. Footnote definitions ([^label]: ...) are NOT included in the results.

Returns:

A vector of FootnoteAnchor entries, each with the label and byte offset.

Signature:

pub fn find_footnote_anchors(markdown: [:0]const u8) []const FootnoteAnchor

Example:

const result = findFootnoteAnchors("value");

Parameters:

Returns: []const FootnoteAnchor

parseFootnoteDefinitions()¶

Parse footnote definitions from markdown text.

Returns a vector of footnote definitions found in the markdown. Handles multi-line definitions with continuation/indented lines (CommonMark format).

Returns:

A vector of FootnoteDefinition entries, each with label, content, and byte offset.

Signature:

pub fn parse_footnote_definitions(markdown: [:0]const u8) []const FootnoteDefinition

Example:

const result = parseFootnoteDefinitions("value");

Parameters:

Returns: []const FootnoteDefinition

findInferenceMarkers()¶

Find inference markers in markdown text.

Returns byte offsets of every [*inference*] marker found in the text.

Returns:

A vector of byte offsets where inference markers appear.

Signature:

pub fn find_inference_markers(markdown: [:0]const u8) []const u64

Example:

const result = findInferenceMarkers("value");

Parameters:

Returns: []const u64

findUnmarkedClaims()¶

Find unmarked claims in markdown text.

Returns lines that assert a claim but carry neither a footnote citation anchor ([^...]) nor an inference marker ([*inference*]).

The heuristic is simple: a line that contains alphabetic words, ends with sentence punctuation, and is not a heading, blank line, or markup-only line is considered a claim. Exclude lines that appear in the citation block (after --- + <!-- citations ... -->).

Returns:

A vector of trimmed line text strings for unmarked claims.

Signature:

pub fn find_unmarked_claims(markdown: [:0]const u8) []const [:0]const u8

Example:

const result = findUnmarkedClaims("value");

Parameters:

Returns: []const [:0]const u8

parseCitations()¶

Parse the structured citation block from markdown.

Extracts citations from the block after a --- thematic break followed by <!-- citations ... --> comment. Parses each entry as: [^srcN]: <source>, <optional-locator>, excerpt: "<text>"

Returns parsed citations with source, optional locator, and optional excerpt.

Returns:

A vector of Citation entries parsed from the citation block.

Signature:

pub fn parse_citations(markdown: [:0]const u8) []const Citation

Example:

const result = parseCitations("value");

Parameters:

Returns: []const Citation

verifyExcerpt()¶

Verify that an excerpt appears verbatim in source text.

Performs exact matching by default. Also tries whitespace-normalized matching (collapsing runs of whitespace on both sides) since PDF-extracted text often has irregular spacing.

Returns:

true if the excerpt appears (exactly or with normalized whitespace), false otherwise.

Signature:

pub fn verify_excerpt(excerpt: [:0]const u8, source_text: [:0]const u8) bool

Example:

const result = verifyExcerpt("value", "value");

Parameters:

Returns: bool

chunkForRag()¶

Chunk text for RAG retrieval, ensuring every chunk carries a heading_path.

Delegates to chunk_text using the caller's config (defaulting to ChunkerType.Markdown when the config uses the default Text type, so that heading hierarchy is resolved). After chunking, derives ChunkMetadata.heading_path from each chunk's heading_context.

underlying splitter; use ChunkerType.Markdown for documents with ATX headings.

Returns:

A ChunkingResult where every chunk's heading_path is populated from its heading_context (empty when the chunk is not under any heading).

Errors:

Propagates any error from the underlying chunker (e.g. invalid overlap).

Signature:

pub fn chunk_for_rag(text: [:0]const u8, config: ChunkingConfig) Error!ChunkingResult

Example:

const result = try chunkForRag("value", .{});

Parameters:

Returns: ChunkingResult

Errors: Throws Error.

compare()¶

Compare two extraction results and return a structured diff.

The comparison is purely structural — no I/O, no side effects. All fields of ExtractionDiff are populated according to the provided DiffOptions.

Signature:

pub fn compare(a: ExtractionResult, b: ExtractionResult, opts: DiffOptions) ExtractionDiff

Example:

const result = compare(.{}, .{}, .{});

Parameters:

Returns: ExtractionDiff

extractRegionWithVlm()¶

Extract content from a pre-cropped image region using a VLM.

The caller is responsible for cropping the page image to the region's bounding box before calling this function. The image_bytes parameter must contain the raw bytes of the cropped region image (JPEG, PNG, WebP, etc.).

Returns:

Extracted Markdown text from the VLM, or an error if the VLM call fails.

Errors:

• Ocr if the VLM call fails or returns no content.
• MissingDependency if the liter-llm client cannot be initialised.

Signature:

pub fn extract_region_with_vlm(image_bytes: []const u8, image_mime: [:0]const u8, region_kind: RegionKind, llm_config: LlmConfig, custom_prompt: ?[:0]const u8) Error![:0]const u8

Example:

const result = try extractRegionWithVlm("data", "value", .{}, .{}, "value");

Parameters:

Returns: [:0]const u8

Errors: Throws Error.

rerankAsync()¶

Rerank documents asynchronously.

Async counterpart to rerank. Offloads blocking ONNX inference to a dedicated blocking thread pool via Tokio's spawn_blocking, keeping the async executor free.

Since v5.0.

Signature:

pub fn rerank_async(query: [:0]const u8, documents: []const [:0]const u8, config: RerankerConfig) Error![]const RerankedDocument

Example:

const result = try rerankAsync("value", &[_]u8{}, .{});

Parameters:

Returns: []const RerankedDocument

Errors: Throws Error.

extractKeywords()¶

Extract keywords from text using the specified algorithm.

This is the unified entry point for keyword extraction. The algorithm used is determined by config.algorithm.

Returns:

A vector of keywords sorted by relevance (highest score first).

Errors:

Returns an error if:

• The specified algorithm feature is not enabled
• Keyword extraction fails

Signature:

pub fn extract_keywords(text: [:0]const u8, config: KeywordConfig) Error![]const Keyword

Example:

const result = try extractKeywords("value", .{});

Parameters:

Returns: []const Keyword

Errors: Throws Error.

analyzeDocument()¶

Analyze a document and determine the optimal chunking strategy.

Decision logic (in priority order):

1. If user provides disable_chunking → no chunking
2. If user provides page_ranges → use user overrides
3. If chunking is not enabled → no chunking
4. If format doesn't support chunking → no chunking
5. If file is small (below both thresholds) and not force_chunking → no chunking

6. If PDF has a substantial text layer AND !force_ocr → no chunking (only when heuristics-pdf feature is enabled; otherwise skipped)

7. Otherwise → chunk the document

Errors:

Returns an error only when the heuristics-pdf feature is active and the PDF text-layer analysis itself returns a hard error. In all other cases the function returns a ChunkingDecision.

Signature:

pub fn analyze_document(metadata: DocumentMetadata, config: HeuristicsConfig, document_bytes: ?[]const u8) Error!ChunkingDecision

Example:

const result = try analyzeDocument(.{}, .{}, "data");

Parameters:

Returns: ChunkingDecision

Errors: Throws Error.

analyzeWithUserChunks()¶

Analyze a document with user-specified chunk ranges.

Creates a chunk plan based on user-provided page ranges.

Signature:

pub fn analyze_with_user_chunks(user_ranges: []const PageRange, total_pages: u32, size_bytes: u64, config: HeuristicsConfig) ChunkingDecision

Example:

const result = analyzeWithUserChunks(&[_]u8{}, 42, 42, .{});

Parameters:

Returns: ChunkingDecision

scoreConfidence()¶

Score a ConfidenceSignals triple into an ExtractionConfidence using the supplied weights.

When signals.ocr_aggregate is null, the OCR weight folds into text_coverage so the weighted sum still totals 1.0.

Signature:

pub fn score_confidence(signals: ConfidenceSignals, weights: ConfidenceWeights) ExtractionConfidence

Example:

const result = scoreConfidence(.{}, .{});

Parameters:

Returns: ExtractionConfidence

checkFormatLimits()¶

Decision returned for pre-extraction rejection based on XLSX/PPTX-specific resource bounds. Returns Some(reason) to reject; null to proceed.

Callers must provide counts from a pre-extraction peek (e.g. parsing xl/workbook.xml for sheet count).

Signature:

pub fn check_format_limits(mime_type: [:0]const u8, sheet_count: ?u32, workbook_cells: ?u64, embedded_count: ?u32, config: HeuristicsConfig) ?[:0]const u8

Example:

const result = checkFormatLimits("value", 42, 42, 42, .{});

Parameters:

Returns: ?[:0]const u8

boundariesFromExtractionResult()¶

Derive document boundaries from an already-produced ExtractionResult.

Builds a MultidocInput from result.pages (one PageSignals per PageContent entry), then delegates to detect_boundaries.

Fallback behaviour¶

• If result.pages is null or empty the whole document is treated as a single document: returns [Start(1), End(1)], matching the contract of detect_boundaries for a one-page input.

Text density¶

PageContent does not carry a pre-computed density score. This function approximates density as non_whitespace_chars / total_chars (clamped to [0.0, 1.0]), which is a reasonable proxy for how text-dense a page is relative to itself. Pass a custom MultidocInput to detect_boundaries directly when you need a higher-fidelity density measurement (e.g. chars-per-pt² from a PDF extractor).

Signature:

pub fn boundaries_from_extraction_result(result: ExtractionResult, thresholds: MultidocThresholds) []const DocumentBoundary

Example:

const result = boundariesFromExtractionResult(.{}, .{});

Parameters:

Returns: []const DocumentBoundary

detectBoundaries()¶

Detect document boundaries in a multi-document PDF.

Returns a list of detected boundaries, always including implicit boundaries at start (page 1) and end (page_count). Boundaries are returned in ascending order of start_page.

Returns:

Ordered list of document boundaries.

Signature:

pub fn detect_boundaries(input: MultidocInput, thresholds: MultidocThresholds) []const DocumentBoundary

Example:

const result = detectBoundaries(.{}, .{});

Parameters:

Returns: []const DocumentBoundary

chooseCallMode()¶

Decide which call mode best fits this document.

Rules applied in order:

1. image/* → StructuredCallMode.VisionOnly (no text layer to start from).

2. application/pdf → StructuredCallMode.TextOnly regardless of text_coverage or embedded image count. Kreuzberg's OCR + text-layer extraction produces text for scanned PDFs; the orchestrator's post-call confidence gate handles any vision escalation actually needed.

3. DOCX / text/html / text/* / application/json / application/xml / application/rtf with avg_chars_per_page > docx_text_min_density → StructuredCallMode.TextOnly.

4. Anything else → StructuredCallMode.Skip.

After rule selection two post-rule promotions apply (in order):

• user_force_vision promotes TextOnly → TextPlusVision (Skip stays Skip — caller meant to opt out).

• enable_vision_fallback promotes TextOnly → TextOnlyWithVisionFallback (does not upgrade TextPlusVision or Skip).

Signature:

pub fn choose_call_mode(input: StructuredInput, t: StructuredThresholds) StructuredCallMode

Example:

const result = chooseCallMode(.{}, .{});

Parameters:

Returns: StructuredCallMode

calculateChunkPlan()¶

Calculate a chunking plan for a document.

Returns:

A ChunkPlan with optimal chunk boundaries.

Signature:

pub fn calculate_chunk_plan(page_count: u32, size_bytes: u64, needs_ocr: bool, config: HeuristicsConfig) ChunkPlan

Example:

const result = calculateChunkPlan(42, 42, true, .{});

Parameters:

Returns: ChunkPlan

calculatePlanFromOverrides()¶

Calculate a chunk plan from user-specified page ranges.

Validates and processes user overrides into a proper chunk plan.

Signature:

pub fn calculate_plan_from_overrides(user_chunks: []const PageRange, total_pages: u32, size_bytes: u64, config: HeuristicsConfig) ChunkPlan

Example:

const result = calculatePlanFromOverrides(&[_]u8{}, 42, 42, .{});

Parameters:

Returns: ChunkPlan

fingerprint()¶

Stable sha256 fingerprint of raw, formatted as sha256:<hex>.

Signature:

pub fn fingerprint(raw: []const u8) [:0]const u8

Example:

const result = fingerprint("data");

Parameters:

Returns: [:0]const u8

resolve()¶

Resolve (preset, custom_schema_override, context) into a ResolvedPreset.

• custom_schema overrides preset.schema when set.
• context substitutes {{key}} tokens in preset.context_template; the rendered string is appended to system_prompt so the model sees it.

Signature:

pub fn resolve(preset: Preset, custom_schema: ?[:0]const u8, context: std.StringHashMap([:0]const u8)) ResolveError!ResolvedPreset

Example:

const result = try resolve(.{}, .{}, .{});

Parameters:

Returns: ResolvedPreset

Errors: Throws ResolveError.

extractStructuredJson()¶

Extract structured JSON from a document using JSON-encoded preset spec and options.

This is the synchronous JSON-in / JSON-out entry point suitable for FFI and language-binding call paths.

cache). Pass "{}" to use all defaults.

Returns:

JSON-serialised StructuredOutput on success.

Errors:

Returns Validation when either JSON argument is malformed. All other failures from the underlying extract_structured_sync call are mapped onto KreuzbergError via From<StructuredError>.

Signature:

pub fn extract_structured_json(bytes: []const u8, mime: [:0]const u8, preset_spec_json: [:0]const u8, options_json: [:0]const u8) Error![:0]const u8

Example:

const result = try extractStructuredJson("data", "value", "value", "value");

Parameters:

Returns: [:0]const u8

Errors: Throws Error.

splitAndExtractJson()¶

Split a multi-document PDF and extract structured JSON from each segment, returning a JSON array of StructuredOutput objects.

Non-PDF documents are passed through as a single-element array.

Same as extract_structured_json.

Returns:

JSON-serialised []const StructuredOutput (a JSON array) on success.

Errors:

Returns Validation when either JSON argument is malformed. All other failures from the underlying split_and_extract_sync call are mapped onto KreuzbergError via From<StructuredError>.

Signature:

pub fn split_and_extract_json(bytes: []const u8, mime: [:0]const u8, preset_spec_json: [:0]const u8, options_json: [:0]const u8) Error![:0]const u8

Example:

const result = try splitAndExtractJson("data", "value", "value", "value");

Parameters:

Returns: [:0]const u8

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.

For pages with extreme dimensions (very wide vector diagrams, etc.) the effective DPI may be automatically reduced to avoid rasterizer failure. A warning is logged when this happens.

Errors:

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

Signature:

pub fn render_pdf_page_to_png(pdf_bytes: []const u8, page_index: u64, dpi: ?i32, password: ?[:0]const u8) Error![]const u8

Example:

const result = try renderPdfPageToPng("data", 42, 42, "value");

Parameters:

Returns: []const u8

Errors: Throws Error.

captionImage()¶

Caption a single image from bytes.

RegionKind.Caption prompt when null.

Returns:

The generated caption text.

Errors:

Returns an error if the VLM call fails or if image format detection fails.

Signature:

pub fn caption_image(image_bytes: []const u8, llm_config: LlmConfig, custom_prompt: ?[:0]const u8) Error![:0]const u8

Example:

const result = try captionImage("data", .{}, "value");

Parameters:

Returns: [:0]const u8

Errors: Throws Error.

captionImageFile()¶

Caption a single image from a file path.

RegionKind.Caption prompt when null.

Returns:

The generated caption text.

Errors:

Returns an error if the file cannot be read, if image format detection fails, or if the VLM call fails.

Signature:

pub fn caption_image_file(path: [:0]const u8, llm_config: LlmConfig, custom_prompt: ?[:0]const u8) Error![:0]const u8

Example:

const result = try captionImageFile("value", .{}, "value");

Parameters:

Returns: [:0]const u8

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:

pub fn detect_mime_type(path: [:0]const u8, check_exists: bool) Error![:0]const u8

Example:

const result = try detectMimeType("value", true);

Parameters:

Returns: [:0]const u8

Errors: Throws Error.

embedTextsAsync()¶

Signature:

pub fn embed_texts_async(texts: []const [:0]const u8, config: EmbeddingConfig) Error![]const []const f32

Example:

const result = try embedTextsAsync(&[_]u8{}, .{});

Parameters:

Returns: []const []const f32

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:

pub fn get_embedding_preset(name: [:0]const u8) ?EmbeddingPreset

Example:

const result = getEmbeddingPreset("value");

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:

pub fn list_embedding_presets() []const [:0]const u8

Example:

const result = listEmbeddingPresets();

Returns: []const [:0]const u8

getEmbeddingPreset()¶

Returns null for builds without the embedding-presets feature.

Signature:

pub fn get_embedding_preset(name: [:0]const u8) ?EmbeddingPreset

Example:

const result = getEmbeddingPreset("value");

Parameters:

Returns: ?EmbeddingPreset

listEmbeddingPresets()¶

Returns an empty list for builds without the embedding-presets feature.

Signature:

pub fn list_embedding_presets() []const [:0]const u8

Example:

const result = listEmbeddingPresets();

Returns: []const [:0]const u8

rerank()¶

Rerank a list of documents by relevance to a query.

Returns documents sorted descending by score. Applies top_k truncation if configured.

Errors:

• KreuzbergError.Validation if query is empty or blank.
• KreuzbergError.MissingDependency if ONNX Runtime is not installed (ONNX path).
• KreuzbergError.Reranking if the preset is unknown or model download fails.

Since v5.0.

Signature:

pub fn rerank(query: [:0]const u8, documents: []const [:0]const u8, config: RerankerConfig) Error![]const RerankedDocument

Example:

const result = try rerank("value", &[_]u8{}, .{});

Parameters:

Returns: []const RerankedDocument

Errors: Throws Error.

rerank()¶

Stub for builds without the reranker feature — keeps the symbol available on no-ORT targets (Android x86_64 emulator, WASM) so language bindings compile.

Since v5.0.

Signature:

pub fn rerank(query: [:0]const u8, documents: []const [:0]const u8, config: RerankerConfig) Error![]const RerankedDocument

Example:

const result = try rerank("value", &[_]u8{}, .{});

Parameters:

Returns: []const RerankedDocument

Errors: Throws Error.

rerankAsync()¶

Stub for builds without the reranker feature.

Since v5.0.

Signature:

pub fn rerank_async(query: [:0]const u8, documents: []const [:0]const u8, config: RerankerConfig) Error![]const RerankedDocument

Example:

const result = try rerankAsync("value", &[_]u8{}, .{});

Parameters:

Returns: []const RerankedDocument

Errors: Throws Error.

getRerankerPreset()¶

Get a reranker 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.

Since v5.0.

Signature:

pub fn get_reranker_preset(name: [:0]const u8) ?RerankerPreset

Example:

const result = getRerankerPreset("value");

Parameters:

Returns: ?RerankerPreset

listRerankerPresets()¶

List the names of all available reranker presets.

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

Since v5.0.

Signature:

pub fn list_reranker_presets() []const [:0]const u8

Example:

const result = listRerankerPresets();

Returns: []const [:0]const u8

getRerankerPreset()¶

Returns null for builds without the reranker-presets feature.

Since v5.0.

Signature:

pub fn get_reranker_preset(name: [:0]const u8) ?RerankerPreset

Example:

const result = getRerankerPreset("value");

Parameters:

Returns: ?RerankerPreset

listRerankerPresets()¶

Returns an empty list for builds without the reranker-presets feature.

Since v5.0.

Signature:

pub fn list_reranker_presets() []const [:0]const u8

Example:

const result = listRerankerPresets();

Returns: []const [:0]const u8

embedTextsAsync()¶

Signature:

pub fn embed_texts_async(texts: []const [:0]const u8, config: EmbeddingConfig) Error![]const []const f32

Example:

const result = try embedTextsAsync(&[_]u8{}, .{});

Parameters:

Returns: []const []const f32

Errors: Throws Error.

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.

AudioMetadata¶

Audio/video file metadata.

Populated from container tags (ID3v2, MP4 atoms, Vorbis comments, etc.) and PCM decode properties. Available when the transcription-types feature is enabled.