Xberg Document Extraction
Xberg is a document intelligence library with a Rust core and bindings for Python, TypeScript/Node.js, Ruby, PHP, Go, Java, C#, Elixir, WebAssembly, Dart, Kotlin Android, Swift, Zig, and C. It extracts text, tables, metadata, and images from 107 formats across 140 unique file extensions and accepts 53 compatibility MIME aliases, including PDF, Office documents, images, HTML, email, archives, and academic formats.
Use this skill when writing code that:
- Extracts text or metadata from documents
- Performs OCR on scanned documents or images
- Batch-processes multiple files
- Configures extraction options (output format, chunking, OCR, language detection)
- Implements custom plugins (post-processors, validators, OCR backends)
If the xberg MCP server is registered in this session, prefer its tools over shelling out to the CLI — they expose the same extraction surface with structured arguments and results.
Installation
Python
pip install xberg
Node.js
npm install @xberg-io/xberg
Rust
cargo add xberg
# Cargo.toml
[dependencies]
xberg = { version = "1.1.0", features = ["full"] }
tokio = { version = "1", features = ["full"] }
# feature flags: pdf, ocr, chunking, embeddings, language-detection, keywords, api, mcp
# (or "formats" / "full" aggregates); tokio-runtime is on by default
CLI
brew install xberg-io/tap/xberg
# or run without a persistent install (the CLI proxy package self-installs the binary):
npx @xberg-io/xberg-cli --help
uvx --from xberg-cli xberg --help
# or download a prebuilt binary from the latest GitHub release:
# https://github.com/xberg-io/xberg/releases/latest
# or build from source:
cargo install xberg-cli
Quick Start
The library entry points are extract(input, config) and extract_batch(inputs, config). Both return an ExtractionResult envelope — the extracted document(s) live in result.results, and per-document data (content, tables, metadata, …) is on each result.results[i]. Python and Node are async-only.
Python
import asyncio
from xberg import ExtractInput, extract, ExtractionConfig
async def main() -> None:
result = await extract(ExtractInput(uri="document.pdf"), ExtractionConfig())
doc = result.results[0]
print(doc.content) # extracted text
print(doc.metadata) # document metadata
print(doc.tables) # extracted tables
asyncio.run(main())
Node.js
import { extract } from "@xberg-io/xberg";
const output = await extract({ kind: "uri", uri: "document.pdf" });
const doc = output.results[0];
console.log(doc.content);
console.log(doc.metadata);
console.log(doc.tables);
Rust
use xberg::{extract, ExtractInput, ExtractionConfig};
#[tokio::main]
async fn main() -> xberg::Result<()> {
let output = extract(ExtractInput::from_uri("document.pdf"), &ExtractionConfig::default()).await?;
println!("{}", output.results[0].content);
Ok(())
}
CLI
xberg extract document.pdf
xberg extract document.pdf --format json
xberg extract document.pdf --content-format markdown
Configuration
All languages use the same configuration structure with language-appropriate naming conventions.
Python (snake_case)
from xberg import (
ExtractInput, extract,
ExtractionConfig, OcrConfig, TesseractConfig, PdfConfig, ChunkingConfig, OutputFormat,
)
config = ExtractionConfig(
ocr=OcrConfig(
backend="tesseract",
language=["eng"],
tesseract_config=TesseractConfig(psm=6, enable_table_detection=True),
),
pdf_options=PdfConfig(passwords=["secret123"]),
chunking=ChunkingConfig(max_characters=1000, overlap=200),
output_format=OutputFormat("markdown"),
)
result = await extract(ExtractInput(uri="document.pdf"), config)
Node.js (camelCase)
import { extract, type ExtractionConfig } from "@xberg-io/xberg";
const config: ExtractionConfig = {
ocr: { backend: "tesseract", language: ["eng"] },
pdfOptions: { passwords: ["secret123"] },
chunking: { maxCharacters: 1000, overlap: 200 },
outputFormat: "markdown",
};
const output = await extract({ kind: "uri", uri: "document.pdf" }, config);
Rust (snake_case)
use xberg::{extract, ExtractInput, ExtractionConfig, OcrConfig, ChunkingConfig, OutputFormat};
let config = ExtractionConfig {
ocr: Some(OcrConfig {
backend: "tesseract".into(),
language: vec!["eng".to_string()],
..Default::default()
}),
chunking: Some(ChunkingConfig {
max_characters: 1000,
overlap: 200,
..Default::default()
}),
output_format: OutputFormat::Markdown,
..Default::default()
};
let output = extract(ExtractInput::from_uri("document.pdf"), &config).await?;
Config File (TOML)
output_format = "markdown"
[ocr]
backend = "tesseract"
language = "eng"
[chunking]
max_characters = 1000
overlap = 200
[pdf_options]
passwords = ["secret123"]
# CLI: auto-discovers xberg.toml in current/parent directories
xberg extract doc.pdf
# or explicit:
xberg extract doc.pdf --config xberg.toml
xberg extract doc.pdf --config-json '{"ocr":{"backend":"tesseract","language":"deu"}}'
Batch Processing
extract_batch takes a list of ExtractInputs and returns one envelope whose results array holds a document per input (in input order); per-input failures are reported in result.errors.
Python
from xberg import ExtractInput, extract_batch, ExtractionConfig
inputs = [
ExtractInput(uri="doc1.pdf"),
ExtractInput(uri="doc2.docx"),
ExtractInput(uri="doc3.xlsx"),
]
output = await extract_batch(inputs, ExtractionConfig())
for doc in output.results:
print(f"{len(doc.content)} chars extracted")
Node.js
import { extractBatch } from "@xberg-io/xberg";
const output = await extractBatch([
{ kind: "uri", uri: "doc1.pdf" },
{ kind: "uri", uri: "doc2.docx" },
]);
for (const doc of output.results) {
console.log(`${doc.content.length} chars`);
}
Rust
use xberg::{extract_batch, ExtractInput, ExtractionConfig};
let config = ExtractionConfig::default();
let inputs = vec![ExtractInput::from_uri("doc1.pdf"), ExtractInput::from_uri("doc2.docx")];
let output = extract_batch(inputs, &config).await?;
CLI
xberg batch *.pdf --format json
xberg batch docs/*.docx --content-format markdown
OCR
OCR runs automatically for images and scanned PDFs. Tesseract is the default backend (native binding, no external install required).
Backends
Select with OcrConfig.backend:
- tesseract (default): built-in native binding. All Tesseract languages supported.
- paddleocr (
"paddleocr" / "paddle-ocr"): ONNX-based PaddleOCR.
- vlm: Vision-Language-Model OCR (configure via
OcrConfig.vlm_config).
Custom backends can be registered in Python/Node via register_ocr_backend (see Advanced Features).
Language Codes
config = ExtractionConfig(ocr=OcrConfig(language=["eng"])) # English
config = ExtractionConfig(ocr=OcrConfig(language=["eng", "deu"])) # Multiple
# The single-string shorthand ("eng+deu") is only accepted in config files / --config-json,
# not in the OcrConfig constructor (Python takes a list, Node takes an array).
Force OCR
config = ExtractionConfig(force_ocr=True) # OCR even if text is extractable
Result Envelope and Document Fields
extract / extract_batch return an ExtractionResult envelope: results (list of documents), errors (per-input failures), and summary (counts). Per-document fields live on each document in results — bind doc = result.results[0] (Python/Node) or &output.results[0] (Rust) first.
| Field |
Python (doc.) |
Node.js (doc.) |
Rust (document.) |
Description |
| Text content |
content |
content |
content |
Extracted text (str/String) |
| MIME type |
mime_type |
mimeType |
mime_type |
Input document MIME type |
| Metadata |
metadata |
metadata |
metadata |
Document metadata (flat mapping) |
| Tables |
tables |
tables |
tables |
Extracted tables with cells + markdown |
| Languages |
detected_languages |
detectedLanguages |
detected_languages |
Detected languages (if enabled) |
| Chunks |
chunks |
chunks |
chunks |
Text chunks (if chunking enabled) |
| Images |
images |
images |
images |
Extracted images (if enabled) |
| Elements |
elements |
elements |
elements |
Semantic elements (if element_based format) |
| Pages |
pages |
pages |
pages |
Per-page content (if page extraction enabled) |
| Keywords |
extracted_keywords |
extractedKeywords |
extracted_keywords |
Extracted keywords (if enabled) |
Error Handling
Python
extract / extract_batch raise a plain RuntimeError on failure — the typed XbergError subclasses are not raised by these entry points, so catch RuntimeError. Per-input failures during extract_batch are reported non-fatally in result.errors.
from xberg import ExtractInput, extract, ExtractionConfig
try:
result = await extract(ExtractInput(uri="file.pdf"), ExtractionConfig())
for err in result.errors:
print(f"Per-input error: {err}")
except RuntimeError as e:
print(f"Extraction failed: {e}")
Node.js
The Node binding throws plain Error objects (it does not export typed error subclasses). Catch with instanceof Error, and inspect output.errors for non-fatal per-input failures.
import { extract } from "@xberg-io/xberg";
try {
const output = await extract({ kind: "uri", uri: "file.pdf" });
if (output.errors.length > 0) {
console.error("Per-input errors:", output.errors);
}
} catch (e) {
if (e instanceof Error) {
console.error(`Extraction failed: ${e.message}`);
}
}
Rust
use xberg::{extract, ExtractInput, ExtractionConfig, XbergError};
let config = ExtractionConfig::default();
match extract(ExtractInput::from_uri("file.pdf"), &config).await {
Ok(output) => println!("{}", output.results[0].content),
Err(XbergError::Parsing { message, .. }) => eprintln!("Parse error: {message}"),
Err(XbergError::Ocr { message, .. }) => eprintln!("OCR error: {message}"),
Err(XbergError::UnsupportedFormat(mime)) => eprintln!("Unsupported: {mime}"),
Err(e) => eprintln!("Error: {e}"),
}
Common Pitfalls
- Result is an envelope:
extract / extract_batch return ExtractionResult with results, errors, and summary. Per-document fields (content, tables, chunks, …) are on result.results[i], NOT on the top-level return.
- Async-only: Python and Node have no sync variants — always
await extract(...). Rust extract is async; use #[tokio::main] or an async context.
- Build the input: pass an
ExtractInput, not a bare path. Use ExtractInput(uri=...) / ExtractInput::from_uri(...) (Python/Rust) or { kind: "uri", uri: "..." } (Node); for bytes use kind="bytes" with bytes/mime_type.
- Python ChunkingConfig fields: construct with
max_characters and overlap (defaults 1000 / 200); these are also the readable attributes. When passing config as a dict/JSON, the max_chars / max_overlap aliases are also accepted. Node uses maxCharacters / overlap; Rust struct fields are max_characters / overlap.
- Python errors:
extract / extract_batch raise a plain RuntimeError on failure, not typed XbergError subclasses — catch RuntimeError. Node throws plain Error (no typed error subclasses).
- Rust extract signature:
extract(input, &config) — the config is a reference. Use &ExtractionConfig::default() for defaults.
- CLI --format vs --content-format:
--format controls CLI output (text, json, or toon). --content-format controls content rendering (plain, markdown, djot, html, json, or doctags).
- Config file field names: Use snake_case in TOML/YAML/JSON config files —
[chunking] fields are max_characters and overlap; other fields use names like output_format, pdf_options.
Supported Formats (Summary)
| Category |
Extensions |
| PDF |
.pdf |
| Word |
.docx, .docm, .doc, .dotx, .dotm, .dot, .odt, .pages, .wpd, .wp, .wp5, .wp6, .hwp, .hwpx |
| Spreadsheets |
.xlsx, .xlsm, .xlsb, .xls, .xla, .xlam, .xltm, .xltx, .xlt, .ods, .numbers |
| Presentations |
.pptx, .pptm, .ppt, .pps, .ppsx, .potx, .potm, .pot, .odp, .key |
| eBooks |
.epub, .fb2 |
| Images |
.png, .jpg, .jpeg, .gif, .webp, .bmp, .tiff, .tif, .jp2, .jpg2, .j2c, .j2k, .jpc, .jbig2, .jb2, .pnm, .pbm, .pgm, .ppm, .heic, .heics, .heif, .heifs, .hif, .avif, .avcs, .svg |
| Markup |
.html, .htm, .xhtml, .xht, .xml, .kml |
| Data |
.json, .geojson, .jsonl, .ndjson, .yaml, .yml, .toml, .csv, .tsv, .dbf, .sqlite, .sqlite3, .db, .gpkg, .gpkx |
| Text |
.txt, .adoc, .asciidoc, .vtt, .md, .markdown, .commonmark, .qmd, .rmd, .mdx, .djot, .dj, .doctags, .rst, .org, .rtf |
| Email |
.eml, .msg, .pst |
| Archives |
.zip, .tar, .tgz, .gz, .7z |
| Audio/Video |
.mp3, .mpga, .m4a, .wav, .webm, .mp4, .mpg4, .mp4v, .m4v, .mpeg, .mpg, .mpe, .m1v, .m2v |
| Academic |
.bib, .ris, .nbib, .enw, .tex, .latex, .typ, .typst, .jats, .nxml, .ipynb, .docbook, .dbk, .docbook4, .docbook5, .opml |
CSL JSON is supported through an explicit MIME type but does not have a registered file extension.
See references/supported-formats.md for the complete format reference with MIME types.
Additional Resources
Detailed reference files for specific topics:
- Python API Reference — All functions, config classes, plugin protocols, exact signatures
- Node.js API Reference — All functions, TypeScript interfaces, worker pool APIs
- Rust API Reference — All functions with feature gates, structs, Cargo.toml examples
- CLI Reference — All commands, flags, config precedence, exit codes
- Configuration Reference — TOML/YAML/JSON formats, auto-discovery, env vars, full schema
- Supported Formats — Format families, extensions, capabilities, and authoritative discovery commands
- Advanced Features — Plugins, embeddings, MCP server, API server, security limits
- Other Language Bindings — Go, Ruby, Java, C#, PHP, Elixir, WASM, Dart, Kotlin Android, Swift, Zig, C, and Docker
Related skills
Task-focused sibling skills go deeper than this overview:
- extracting-with-ocr — OCR backends, language packs, force-OCR, tuning.
- extracting-tables — layout-aware table detection and table models.
- chunking — chunk size/overlap, markdown/yaml/semantic chunkers, the
chunk command.
- extracting-keywords — YAKE/RAKE keywords, language detection, the
embed command.
- batch-extraction — the
batch command, --file-configs, parallelism, error recovery.
- picking-a-format — choosing
--format / --content-format per consumer.
Full documentation: https://docs.xberg.io
GitHub: https://github.com/xberg-io/xberg
1---
2name: xberg
3description: >-
4 Extract text, tables, metadata, and images from 107 document formats
5 (PDF, Office, images, HTML, email, archives, academic) using Xberg.
6 Use when writing code that calls Xberg APIs in Python, Node.js/TypeScript,
7 Rust, or CLI. Covers installation, extraction (sync/async), configuration
8 (OCR, chunking, output format), batch processing, error handling, and plugins.
9license: Elastic-2.0
10metadata:
11 source: https://skillmd.com/skills/xberg-io/xberg
12 author: xberg-io
13 version: "0.1.0"
14 repository: https://github.com/xberg-io/xberg
15---
16
17<!--
18AI-RULEZ :: GENERATED FILE — DO NOT EDIT
19Content-Hash: blake3:a350cdaa08f8e82becd82ed51d10fc81771a4cf74c1b619e65b424101f0a612c
20Source-Hash: blake3:b4d7bed4b4d3a6a30408bf787c69ff09c73a68092ee161ecf2a72f11338b8435
21Schema-Version: v1
22-->
23
24# Xberg Document Extraction
25
26Xberg is a document intelligence library with a Rust core and bindings for Python, TypeScript/Node.js, Ruby, PHP, Go, Java, C#, Elixir, WebAssembly, Dart, Kotlin Android, Swift, Zig, and C. It extracts text, tables, metadata, and images from 107 formats across 140 unique file extensions and accepts 53 compatibility MIME aliases, including PDF, Office documents, images, HTML, email, archives, and academic formats.
27
28Use this skill when writing code that:
29
30- Extracts text or metadata from documents
31- Performs OCR on scanned documents or images
32- Batch-processes multiple files
33- Configures extraction options (output format, chunking, OCR, language detection)
34- Implements custom plugins (post-processors, validators, OCR backends)
35
36> If the `xberg` MCP server is registered in this session, prefer its tools over shelling out to the CLI — they expose the same extraction surface with structured arguments and results.
37
38## Installation
39
40### Python
41
42```bash
43pip install xberg
44```
45
46### Node.js
47
48```bash
49npm install @xberg-io/xberg
50```
51
52### Rust
53
54```bash
55cargo add xberg
56```
57
58```toml
59# Cargo.toml
60[dependencies]
61xberg = { version = "1.1.0", features = ["full"] }
62tokio = { version = "1", features = ["full"] }
63# feature flags: pdf, ocr, chunking, embeddings, language-detection, keywords, api, mcp
64# (or "formats" / "full" aggregates); tokio-runtime is on by default
65```
66
67### CLI
68
69```bash
70brew install xberg-io/tap/xberg
71# or run without a persistent install (the CLI proxy package self-installs the binary):
72npx @xberg-io/xberg-cli --help
73uvx --from xberg-cli xberg --help
74# or download a prebuilt binary from the latest GitHub release:
75# https://github.com/xberg-io/xberg/releases/latest
76# or build from source:
77cargo install xberg-cli
78```
79
80## Quick Start
81
82The library entry points are `extract(input, config)` and `extract_batch(inputs, config)`. Both return an `ExtractionResult` **envelope** — the extracted document(s) live in `result.results`, and per-document data (`content`, `tables`, `metadata`, …) is on each `result.results[i]`. Python and Node are async-only.
83
84### Python
85
86```python
87import asyncio
88from xberg import ExtractInput, extract, ExtractionConfig
89
90async def main() -> None:
91 result = await extract(ExtractInput(uri="document.pdf"), ExtractionConfig())
92 doc = result.results[0]
93 print(doc.content) # extracted text
94 print(doc.metadata) # document metadata
95 print(doc.tables) # extracted tables
96
97asyncio.run(main())
98```
99
100### Node.js
101
102```typescript
103import { extract } from "@xberg-io/xberg";
104
105const output = await extract({ kind: "uri", uri: "document.pdf" });
106const doc = output.results[0];
107console.log(doc.content);
108console.log(doc.metadata);
109console.log(doc.tables);
110```
111
112### Rust
113
114```rust
115use xberg::{extract, ExtractInput, ExtractionConfig};
116
117#[tokio::main]
118async fn main() -> xberg::Result<()> {
119 let output = extract(ExtractInput::from_uri("document.pdf"), &ExtractionConfig::default()).await?;
120 println!("{}", output.results[0].content);
121 Ok(())
122}
123```
124
125### CLI
126
127```bash
128xberg extract document.pdf
129xberg extract document.pdf --format json
130xberg extract document.pdf --content-format markdown
131```
132
133## Configuration
134
135All languages use the same configuration structure with language-appropriate naming conventions.
136
137### Python (snake_case)
138
139```python
140from xberg import (
141 ExtractInput, extract,
142 ExtractionConfig, OcrConfig, TesseractConfig, PdfConfig, ChunkingConfig, OutputFormat,
143)
144
145config = ExtractionConfig(
146 ocr=OcrConfig(
147 backend="tesseract",
148 language=["eng"],
149 tesseract_config=TesseractConfig(psm=6, enable_table_detection=True),
150 ),
151 pdf_options=PdfConfig(passwords=["secret123"]),
152 chunking=ChunkingConfig(max_characters=1000, overlap=200),
153 output_format=OutputFormat("markdown"),
154)
155
156result = await extract(ExtractInput(uri="document.pdf"), config)
157```
158
159### Node.js (camelCase)
160
161```typescript
162import { extract, type ExtractionConfig } from "@xberg-io/xberg";
163
164const config: ExtractionConfig = {
165 ocr: { backend: "tesseract", language: ["eng"] },
166 pdfOptions: { passwords: ["secret123"] },
167 chunking: { maxCharacters: 1000, overlap: 200 },
168 outputFormat: "markdown",
169};
170
171const output = await extract({ kind: "uri", uri: "document.pdf" }, config);
172```
173
174### Rust (snake_case)
175
176```rust
177use xberg::{extract, ExtractInput, ExtractionConfig, OcrConfig, ChunkingConfig, OutputFormat};
178
179let config = ExtractionConfig {
180 ocr: Some(OcrConfig {
181 backend: "tesseract".into(),
182 language: vec!["eng".to_string()],
183 ..Default::default()
184 }),
185 chunking: Some(ChunkingConfig {
186 max_characters: 1000,
187 overlap: 200,
188 ..Default::default()
189 }),
190 output_format: OutputFormat::Markdown,
191 ..Default::default()
192};
193
194let output = extract(ExtractInput::from_uri("document.pdf"), &config).await?;
195```
196
197### Config File (TOML)
198
199```toml
200output_format = "markdown"
201
202[ocr]
203backend = "tesseract"
204language = "eng"
205
206[chunking]
207max_characters = 1000
208overlap = 200
209
210[pdf_options]
211passwords = ["secret123"]
212```
213
214```bash
215# CLI: auto-discovers xberg.toml in current/parent directories
216xberg extract doc.pdf
217# or explicit:
218xberg extract doc.pdf --config xberg.toml
219xberg extract doc.pdf --config-json '{"ocr":{"backend":"tesseract","language":"deu"}}'
220```
221
222## Batch Processing
223
224`extract_batch` takes a list of `ExtractInput`s and returns one envelope whose `results` array holds a document per input (in input order); per-input failures are reported in `result.errors`.
225
226### Python
227
228```python
229from xberg import ExtractInput, extract_batch, ExtractionConfig
230
231inputs = [
232 ExtractInput(uri="doc1.pdf"),
233 ExtractInput(uri="doc2.docx"),
234 ExtractInput(uri="doc3.xlsx"),
235]
236output = await extract_batch(inputs, ExtractionConfig())
237
238for doc in output.results:
239 print(f"{len(doc.content)} chars extracted")
240```
241
242### Node.js
243
244```typescript
245import { extractBatch } from "@xberg-io/xberg";
246
247const output = await extractBatch([
248 { kind: "uri", uri: "doc1.pdf" },
249 { kind: "uri", uri: "doc2.docx" },
250]);
251for (const doc of output.results) {
252 console.log(`${doc.content.length} chars`);
253}
254```
255
256### Rust
257
258```rust
259use xberg::{extract_batch, ExtractInput, ExtractionConfig};
260
261let config = ExtractionConfig::default();
262let inputs = vec![ExtractInput::from_uri("doc1.pdf"), ExtractInput::from_uri("doc2.docx")];
263let output = extract_batch(inputs, &config).await?;
264```
265
266### CLI
267
268```bash
269xberg batch *.pdf --format json
270xberg batch docs/*.docx --content-format markdown
271```
272
273## OCR
274
275OCR runs automatically for images and scanned PDFs. Tesseract is the default backend (native binding, no external install required).
276
277### Backends
278
279Select with `OcrConfig.backend`:
280
281- **tesseract** (default): built-in native binding. All Tesseract languages supported.
282- **paddleocr** (`"paddleocr"` / `"paddle-ocr"`): ONNX-based PaddleOCR.
283- **vlm**: Vision-Language-Model OCR (configure via `OcrConfig.vlm_config`).
284
285Custom backends can be registered in Python/Node via `register_ocr_backend` (see [Advanced Features](references/advanced-features.md)).
286
287### Language Codes
288
289```python
290config = ExtractionConfig(ocr=OcrConfig(language=["eng"])) # English
291config = ExtractionConfig(ocr=OcrConfig(language=["eng", "deu"])) # Multiple
292# The single-string shorthand ("eng+deu") is only accepted in config files / --config-json,
293# not in the OcrConfig constructor (Python takes a list, Node takes an array).
294```
295
296### Force OCR
297
298```python
299config = ExtractionConfig(force_ocr=True) # OCR even if text is extractable
300```
301
302## Result Envelope and Document Fields
303
304`extract` / `extract_batch` return an `ExtractionResult` envelope: `results` (list of documents), `errors` (per-input failures), and `summary` (counts). Per-document fields live on each document in `results` — bind `doc = result.results[0]` (Python/Node) or `&output.results[0]` (Rust) first.
305
306| Field | Python (`doc.`) | Node.js (`doc.`) | Rust (`document.`) | Description |
307| ------------ | ---------------------- | --------------------- | ----------------------- | --------------------------------------------- |
308| Text content | `content` | `content` | `content` | Extracted text (str/String) |
309| MIME type | `mime_type` | `mimeType` | `mime_type` | Input document MIME type |
310| Metadata | `metadata` | `metadata` | `metadata` | Document metadata (flat mapping) |
311| Tables | `tables` | `tables` | `tables` | Extracted tables with cells + markdown |
312| Languages | `detected_languages` | `detectedLanguages` | `detected_languages` | Detected languages (if enabled) |
313| Chunks | `chunks` | `chunks` | `chunks` | Text chunks (if chunking enabled) |
314| Images | `images` | `images` | `images` | Extracted images (if enabled) |
315| Elements | `elements` | `elements` | `elements` | Semantic elements (if element_based format) |
316| Pages | `pages` | `pages` | `pages` | Per-page content (if page extraction enabled) |
317| Keywords | `extracted_keywords` | `extractedKeywords` | `extracted_keywords` | Extracted keywords (if enabled) |
318
319## Error Handling
320
321### Python
322
323`extract` / `extract_batch` raise a plain `RuntimeError` on failure — the typed `XbergError` subclasses are not raised by these entry points, so catch `RuntimeError`. Per-input failures during `extract_batch` are reported non-fatally in `result.errors`.
324
325```python
326from xberg import ExtractInput, extract, ExtractionConfig
327
328try:
329 result = await extract(ExtractInput(uri="file.pdf"), ExtractionConfig())
330 for err in result.errors:
331 print(f"Per-input error: {err}")
332except RuntimeError as e:
333 print(f"Extraction failed: {e}")
334```
335
336### Node.js
337
338The Node binding throws plain `Error` objects (it does not export typed error subclasses). Catch with `instanceof Error`, and inspect `output.errors` for non-fatal per-input failures.
339
340```typescript
341import { extract } from "@xberg-io/xberg";
342
343try {
344 const output = await extract({ kind: "uri", uri: "file.pdf" });
345 if (output.errors.length > 0) {
346 console.error("Per-input errors:", output.errors);
347 }
348} catch (e) {
349 if (e instanceof Error) {
350 console.error(`Extraction failed: ${e.message}`);
351 }
352}
353```
354
355### Rust
356
357```rust
358use xberg::{extract, ExtractInput, ExtractionConfig, XbergError};
359
360let config = ExtractionConfig::default();
361match extract(ExtractInput::from_uri("file.pdf"), &config).await {
362 Ok(output) => println!("{}", output.results[0].content),
363 Err(XbergError::Parsing { message, .. }) => eprintln!("Parse error: {message}"),
364 Err(XbergError::Ocr { message, .. }) => eprintln!("OCR error: {message}"),
365 Err(XbergError::UnsupportedFormat(mime)) => eprintln!("Unsupported: {mime}"),
366 Err(e) => eprintln!("Error: {e}"),
367}
368```
369
370## Common Pitfalls
371
3721. **Result is an envelope**: `extract` / `extract_batch` return `ExtractionResult` with `results`, `errors`, and `summary`. Per-document fields (`content`, `tables`, `chunks`, …) are on `result.results[i]`, NOT on the top-level return.
3732. **Async-only**: Python and Node have no sync variants — always `await extract(...)`. Rust `extract` is async; use `#[tokio::main]` or an async context.
3743. **Build the input**: pass an `ExtractInput`, not a bare path. Use `ExtractInput(uri=...)` / `ExtractInput::from_uri(...)` (Python/Rust) or `{ kind: "uri", uri: "..." }` (Node); for bytes use `kind="bytes"` with `bytes`/`mime_type`.
3754. **Python ChunkingConfig fields**: construct with `max_characters` and `overlap` (defaults 1000 / 200); these are also the readable attributes. When passing config as a dict/JSON, the `max_chars` / `max_overlap` aliases are also accepted. Node uses `maxCharacters` / `overlap`; Rust struct fields are `max_characters` / `overlap`.
3765. **Python errors**: `extract` / `extract_batch` raise a plain `RuntimeError` on failure, not typed `XbergError` subclasses — catch `RuntimeError`. Node throws plain `Error` (no typed error subclasses).
3776. **Rust extract signature**: `extract(input, &config)` — the config is a reference. Use `&ExtractionConfig::default()` for defaults.
3787. **CLI --format vs --content-format**: `--format` controls CLI output (`text`, `json`, or `toon`). `--content-format` controls content rendering (`plain`, `markdown`, `djot`, `html`, `json`, or `doctags`).
3798. **Config file field names**: Use snake_case in TOML/YAML/JSON config files — `[chunking]` fields are `max_characters` and `overlap`; other fields use names like `output_format`, `pdf_options`.
380
381## Supported Formats (Summary)
382
383| Category | Extensions |
384| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
385| **PDF** | `.pdf` |
386| **Word** | `.docx`, `.docm`, `.doc`, `.dotx`, `.dotm`, `.dot`, `.odt`, `.pages`, `.wpd`, `.wp`, `.wp5`, `.wp6`, `.hwp`, `.hwpx` |
387| **Spreadsheets** | `.xlsx`, `.xlsm`, `.xlsb`, `.xls`, `.xla`, `.xlam`, `.xltm`, `.xltx`, `.xlt`, `.ods`, `.numbers` |
388| **Presentations** | `.pptx`, `.pptm`, `.ppt`, `.pps`, `.ppsx`, `.potx`, `.potm`, `.pot`, `.odp`, `.key` |
389| **eBooks** | `.epub`, `.fb2` |
390| **Images** | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, `.tiff`, `.tif`, `.jp2`, `.jpg2`, `.j2c`, `.j2k`, `.jpc`, `.jbig2`, `.jb2`, `.pnm`, `.pbm`, `.pgm`, `.ppm`, `.heic`, `.heics`, `.heif`, `.heifs`, `.hif`, `.avif`, `.avcs`, `.svg` |
391| **Markup** | `.html`, `.htm`, `.xhtml`, `.xht`, `.xml`, `.kml` |
392| **Data** | `.json`, `.geojson`, `.jsonl`, `.ndjson`, `.yaml`, `.yml`, `.toml`, `.csv`, `.tsv`, `.dbf`, `.sqlite`, `.sqlite3`, `.db`, `.gpkg`, `.gpkx` |
393| **Text** | `.txt`, `.adoc`, `.asciidoc`, `.vtt`, `.md`, `.markdown`, `.commonmark`, `.qmd`, `.rmd`, `.mdx`, `.djot`, `.dj`, `.doctags`, `.rst`, `.org`, `.rtf` |
394| **Email** | `.eml`, `.msg`, `.pst` |
395| **Archives** | `.zip`, `.tar`, `.tgz`, `.gz`, `.7z` |
396| **Audio/Video** | `.mp3`, `.mpga`, `.m4a`, `.wav`, `.webm`, `.mp4`, `.mpg4`, `.mp4v`, `.m4v`, `.mpeg`, `.mpg`, `.mpe`, `.m1v`, `.m2v` |
397| **Academic** | `.bib`, `.ris`, `.nbib`, `.enw`, `.tex`, `.latex`, `.typ`, `.typst`, `.jats`, `.nxml`, `.ipynb`, `.docbook`, `.dbk`, `.docbook4`, `.docbook5`, `.opml` |
398
399CSL JSON is supported through an explicit MIME type but does not have a registered file extension.
400
401See [references/supported-formats.md](references/supported-formats.md) for the complete format reference with MIME types.
402
403## Additional Resources
404
405Detailed reference files for specific topics:
406
407- **[Python API Reference](references/python-api.md)** — All functions, config classes, plugin protocols, exact signatures
408- **[Node.js API Reference](references/nodejs-api.md)** — All functions, TypeScript interfaces, worker pool APIs
409- **[Rust API Reference](references/rust-api.md)** — All functions with feature gates, structs, Cargo.toml examples
410- **[CLI Reference](references/cli-reference.md)** — All commands, flags, config precedence, exit codes
411- **[Configuration Reference](references/configuration.md)** — TOML/YAML/JSON formats, auto-discovery, env vars, full schema
412- **[Supported Formats](references/supported-formats.md)** — Format families, extensions, capabilities, and authoritative discovery commands
413- **[Advanced Features](references/advanced-features.md)** — Plugins, embeddings, MCP server, API server, security limits
414- **[Other Language Bindings](references/other-bindings.md)** — Go, Ruby, Java, C#, PHP, Elixir, WASM, Dart, Kotlin Android, Swift, Zig, C, and Docker
415
416## Related skills
417
418Task-focused sibling skills go deeper than this overview:
419
420- **extracting-with-ocr** — OCR backends, language packs, force-OCR, tuning.
421- **extracting-tables** — layout-aware table detection and table models.
422- **chunking** — chunk size/overlap, markdown/yaml/semantic chunkers, the `chunk` command.
423- **extracting-keywords** — YAKE/RAKE keywords, language detection, the `embed` command.
424- **batch-extraction** — the `batch` command, `--file-configs`, parallelism, error recovery.
425- **picking-a-format** — choosing `--format` / `--content-format` per consumer.
426
427Full documentation: <https://docs.xberg.io>
428GitHub: <https://github.com/xberg-io/xberg>