Rust API Reference

pub async fn extract_bytes(content: &[u8], mime_type: &str, config: ExtractionConfig) -> Result<ExtractionResult, Error>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | `Vec<u8>` | Yes | The byte array to extract |
| `mime_type` | `String` | Yes | MIME type of the content |
| `config` | `ExtractionConfig` | Yes | Extraction configuration |

**Returns:** `ExtractionResult`

**Errors:** Returns `Err(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:**

```rust
pub async fn extract_file(path: PathBuf, mime_type: Option<String>, config: ExtractionConfig) -> Result<ExtractionResult, Error>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | `PathBuf` | Yes | Path to the file to extract |
| `mime_type` | `Option<String>` | No | Optional MIME type override. If None, will be auto-detected |
| `config` | `ExtractionConfig` | Yes | Extraction configuration |

**Returns:** `ExtractionResult`

**Errors:** Returns `Err(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:**

```rust
pub fn extract_file_sync(path: PathBuf, mime_type: Option<String>, config: ExtractionConfig) -> Result<ExtractionResult, Error>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | `PathBuf` | Yes | Path to the file |
| `mime_type` | `Option<String>` | No | The mime type |
| `config` | `ExtractionConfig` | Yes | The configuration options |

**Returns:** `ExtractionResult`

**Errors:** Returns `Err(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:**

```rust
pub fn extract_bytes_sync(content: &[u8], mime_type: &str, config: ExtractionConfig) -> Result<ExtractionResult, Error>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | `Vec<u8>` | Yes | The content to process |
| `mime_type` | `String` | Yes | The mime type |
| `config` | `ExtractionConfig` | Yes | The configuration options |

**Returns:** `ExtractionResult`

**Errors:** Returns `Err(Error)`.

---

#### extract_bytes_sync()

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

```rust
pub fn extract_bytes_sync(content: &[u8], mime_type: &str, config: ExtractionConfig) -> Result<ExtractionResult, Error>

let result = extract_bytes_sync(b"data", "value", ExtractionConfig::default())?;

pub fn batch_extract_files_sync(items: Vec<BatchFileItem>, config: ExtractionConfig) -> Result<Vec<ExtractionResult>, Error>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | `Vec<BatchFileItem>` | Yes | The items |
| `config` | `ExtractionConfig` | Yes | The configuration options |

**Returns:** `Vec<ExtractionResult>`

**Errors:** Returns `Err(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:**

```rust
pub fn batch_extract_bytes_sync(items: Vec<BatchBytesItem>, config: ExtractionConfig) -> Result<Vec<ExtractionResult>, Error>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | `Vec<BatchBytesItem>` | Yes | The items |
| `config` | `ExtractionConfig` | Yes | The configuration options |

**Returns:** `Vec<ExtractionResult>`

**Errors:** Returns `Err(Error)`.

---

#### batch_extract_bytes_sync()

Synchronous wrapper for `batch_extract_bytes` (WASM-compatible version).

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

**Signature:**

```rust
pub fn batch_extract_bytes_sync(items: Vec<BatchBytesItem>, config: ExtractionConfig) -> Result<Vec<ExtractionResult>, Error>

let result = batch_extract_bytes_sync(vec![], ExtractionConfig::default())?;

pub async fn batch_extract_files(items: Vec<BatchFileItem>, config: ExtractionConfig) -> Result<Vec<ExtractionResult>, Error>

Per-file configuration overrides:

```rust,no_run
use kreuzberg::core::extractor::batch_extract_files;
use kreuzberg::core::config::{ExtractionConfig, BatchFileItem, FileExtractionConfig};
use std::path::PathBuf;

let config = ExtractionConfig::default();
let items = vec![
    BatchFileItem {
        path: "scan.pdf".into(),
        config: Some(FileExtractionConfig { force_ocr: Some(true), ..Default::default() }),
    },
    BatchFileItem { path: "notes.txt".into(), config: None },
];
let results = batch_extract_files(items, &config).await?;
```rust

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | `Vec<BatchFileItem>` | Yes | Vector of `BatchFileItem` structs, each containing a path and optional |
| `config` | `ExtractionConfig` | Yes | Batch-level extraction configuration (provides defaults and batch settings) |

**Returns:** `Vec<ExtractionResult>`

**Errors:** Returns `Err(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:**

```rust
pub async fn batch_extract_bytes(items: Vec<BatchBytesItem>, config: ExtractionConfig) -> Result<Vec<ExtractionResult>, Error>

Per-item configuration overrides:

```rust,no_run
use kreuzberg::core::extractor::batch_extract_bytes;
use kreuzberg::core::config::{ExtractionConfig, BatchBytesItem, FileExtractionConfig};

let config = ExtractionConfig::default();
let items = vec![
    BatchBytesItem { content: b"content".to_vec(), mime_type: "text/plain".to_string(), config: None },
    BatchBytesItem {
        content: b"<html>test</html>".to_vec(),
        mime_type: "text/html".to_string(),
        config: Some(FileExtractionConfig { force_ocr: Some(true), ..Default::default() }),
    },
];
let results = batch_extract_bytes(items, &config).await?;
```rust

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `items` | `Vec<BatchBytesItem>` | Yes | Vector of `BatchBytesItem` structs, each containing content bytes, |
| `config` | `ExtractionConfig` | Yes | Batch-level extraction configuration |

**Returns:** `Vec<ExtractionResult>`

**Errors:** Returns `Err(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:**

```rust
pub fn detect_mime_type_from_bytes(content: &[u8]) -> Result<String, Error>

let result = detect_mime_type_from_bytes(b"data")?;

pub fn get_extensions_for_mime(mime_type: &str) -> Result<Vec<String>, Error>

use kreuzberg::core::mime::get_extensions_for_mime;

let extensions = get_extensions_for_mime("application/pdf").unwrap();
assert_eq!(extensions, vec!["pdf"]);

let doc_extensions = get_extensions_for_mime("application/vnd.openxmlformats-officedocument.wordprocessingml.document").unwrap();
assert!(doc_extensions.contains(&"docx".to_string()));
```rust

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mime_type` | `String` | Yes | The MIME type to look up |

**Returns:** `Vec<String>`

**Errors:** Returns `Err(Error)`.

---

#### list_supported_formats()

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

```rust
pub fn list_supported_formats() -> Vec<SupportedFormat>

use kreuzberg::core::mime::list_supported_formats;

let formats = list_supported_formats();
assert!(!formats.is_empty());
assert!(formats.iter().any(|f| f.extension == "pdf"));
```rust

**Returns:** `Vec<SupportedFormat>`

---

#### detect_qr_codes()

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 vector 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:**

```rust
pub fn detect_qr_codes(image_bytes: &[u8], format_hint: Option<String>) -> Vec<QrCode>

let result = detect_qr_codes(b"data", "value");

pub fn clear_embedding_backends() -> Result<(), Error>

clear_embedding_backends()?;

pub fn list_embedding_backends() -> Result<Vec<String>, Error>

let result = list_embedding_backends()?;

pub fn list_document_extractors() -> Result<Vec<String>, Error>

let result = list_document_extractors()?;

pub fn clear_document_extractors() -> Result<(), Error>

clear_document_extractors()?;

pub fn list_ocr_backends() -> Result<Vec<String>, Error>

use kreuzberg::plugins::list_ocr_backends;

let backends = list_ocr_backends()?;
for name in backends {
    println!("Registered OCR backend: {}", name);
}
```rust

**Returns:** `Vec<String>`

**Errors:** Returns `Err(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:**

```rust
pub fn clear_ocr_backends() -> Result<(), Error>

use kreuzberg::plugins::clear_ocr_backends;

clear_ocr_backends()?;
```rust

**Returns:** No return value.

**Errors:** Returns `Err(Error)`.

---

#### register_builtin()

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

```rust
pub fn register_builtin() -> Result<(), Error>

register_builtin()?;

pub fn list_post_processors() -> Result<Vec<String>, Error>

use kreuzberg::plugins::list_post_processors;

let processors = list_post_processors()?;
for name in processors {
    println!("Registered post-processor: {}", name);
}
```rust

**Returns:** `Vec<String>`

**Errors:** Returns `Err(Error)`.

---

#### clear_post_processors()

Remove all registered post-processors.

**Signature:**

```rust
pub fn clear_post_processors() -> Result<(), Error>

clear_post_processors()?;

pub fn list_renderers() -> Result<Vec<String>, Error>

let result = list_renderers()?;

pub fn clear_renderers() -> Result<(), Error>

clear_renderers()?;

pub fn clear_reranker_backends() -> Result<(), Error>

clear_reranker_backends()?;

pub fn list_reranker_backends() -> Result<Vec<String>, Error>

let result = list_reranker_backends()?;

pub fn list_validators() -> Result<Vec<String>, Error>

let result = list_validators()?;

pub fn clear_validators() -> Result<(), Error>

clear_validators()?;

pub async fn classify_pages(result: ExtractionResult, config: PageClassificationConfig) -> Result<(), Error>

classify_pages(ExtractionResult::default(), PageClassificationConfig::default()).await?;

pub async fn classify_text(text: &str, config: PageClassificationConfig) -> Result<Vec<ClassificationLabel>, Error>

let result = classify_text("value", PageClassificationConfig::default()).await?;

pub async fn classify_document(pages: Vec<String>, config: PageClassificationConfig) -> Result<Vec<ClassificationLabel>, Error>

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pages` | `Vec<String>` | Yes | Slice of page texts to classify. Each page is classified independently |
| `config` | `PageClassificationConfig` | Yes | Classification configuration including labels and LLM settings. |

**Returns:** `Vec<ClassificationLabel>`

**Errors:** Returns `Err(Error)`.

---

#### download_model()

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

```rust
pub fn download_model(name: &str, cache_dir: Option<PathBuf>) -> Result<PathBuf, Error>

let result = download_model("value", "value")?;

pub fn download_model(name: &str, cache_dir: Option<PathBuf>) -> Result<PathBuf, Error>

let result = download_model("value", "value")?;

pub fn default_model_name() -> String

let result = default_model_name();

pub fn default_model_name() -> String

let result = default_model_name();

pub fn known_models() -> Vec<String>

let result = known_models();

pub fn known_models() -> Vec<String>

let result = known_models();

pub fn download_model(name: &str, cache_dir: Option<PathBuf>) -> Result<PathBuf, Error>

let result = download_model("value", "value")?;

pub fn default_model_name() -> String

let result = default_model_name();

pub fn known_models() -> Vec<String>

let result = known_models();

pub async fn redact(result: ExtractionResult, config: RedactionConfig) -> Result<(), Error>

redact(ExtractionResult::default(), RedactionConfig::default()).await?;

pub fn find_all(text: &str) -> Vec<PatternMatch>

let result = find_all("value");

pub fn scan_text(text: &str, categories: Vec<PiiCategory>) -> Vec<PatternMatch>

let result = scan_text("value", vec![]);

pub fn summarize(text: &str, language: Option<String>, max_tokens: Option<u32>) -> Option<String>

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

pub fn token_count(text: &str) -> u32

let result = token_count("value");

pub async fn translate_result(result: ExtractionResult, config: TranslationConfig) -> Result<(), Error>

translate_result(ExtractionResult::default(), TranslationConfig::default()).await?;

pub fn find_footnote_anchors(markdown: &str) -> Vec<FootnoteAnchor>

let text = "Text[^src1] more text[^src2].";
let anchors = find_footnote_anchors(text);
assert_eq!(anchors.len(), 2);
assert_eq!(anchors[0].label, "src1");
assert_eq!(anchors[1].label, "src2");
```rust

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `markdown` | `String` | Yes | The markdown text to search |

**Returns:** `Vec<FootnoteAnchor>`

---

#### parse_footnote_definitions()

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

```rust
pub fn parse_footnote_definitions(markdown: &str) -> Vec<FootnoteDefinition>

let text = r#"[^1]: First footnote.
[^2]: Second footnote.
  Continued line."#;
let defs = parse_footnote_definitions(text);
assert_eq!(defs.len(), 2);
```rust

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `markdown` | `String` | Yes | The markdown text to search |

**Returns:** `Vec<FootnoteDefinition>`

---

#### find_inference_markers()

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

```rust
pub fn find_inference_markers(markdown: &str) -> Vec<usize>

let text = "A claim [*inference*] with inference marker.";
let offsets = find_inference_markers(text);
assert_eq!(offsets.len(), 1);
```rust

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `markdown` | `String` | Yes | The markdown text to search |

**Returns:** `Vec<usize>`

---

#### find_unmarked_claims()

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

```rust
pub fn find_unmarked_claims(markdown: &str) -> Vec<String>