Configuration Guide

All extraction behavior is controlled through ExtractionConfig. Pass it directly in code or load it from a TOML/YAML/JSON file. Every field is optional. For per-field documentation, see the Configuration Reference.

Quick Start

import asyncio
from xberg import ExtractInput, extract, ExtractionConfig

async def main() -> None:
    config = ExtractionConfig(
        use_cache=True,
        enable_quality_processing=True
    )
    result = await extract(ExtractInput(uri="document.pdf"), config)
    print(result.results[0].content)

asyncio.run(main())

import { ExtractInputKind, extract } from "@xberg-io/xberg";

const config = {
  useCache: true,
  enableQualityProcessing: true,
};

const output = await extract({ kind: ExtractInputKind.Uri, uri: "document.pdf" }, config);
console.log(output.results?.[0]?.content);

use xberg::{extract, ExtractionConfig, ExtractInput};

#[tokio::main]
async fn main() -> xberg::Result<()> {
    let config = ExtractionConfig {
        use_cache: true,
        enable_quality_processing: true,
        ..Default::default()
    };

    let output = extract(ExtractInput::from_uri("document.pdf"), &config).await?;
    println!("{}", output.results[0].content);
    Ok(())
}

package main

import (
  "log"

  "github.com/xberg-io/xberg/packages/go"
)

func main() {
  useCache := true
  enableQP := true

  cfg := xberg.ExtractionConfig{
    UseCache:                &useCache,
    EnableQualityProcessing: &enableQP,
  }
  input := xberg.ExtractInputFromURI("document.pdf")
  result, err := xberg.Extract(*input, cfg)
  if err != nil {
    log.Fatalf("extract failed: %v", err)
  }

  log.Println("content length:", len(result.Results[0].Content))
}

import io.xberg.Xberg;
import io.xberg.ExtractInputKind;
import io.xberg.ExtractionResult;
import io.xberg.ExtractedDocument;
import io.xberg.ExtractionConfig;
import io.xberg.ExtractInput;

ExtractionConfig config = ExtractionConfig.builder()
    .withUseCache(true)
    .withEnableQualityProcessing(true)
    .build();
ExtractionResult output = Xberg.extract(
    ExtractInput.builder().withKind(ExtractInputKind.URI).withUri("document.pdf").build(),
    config
);
ExtractedDocument result = output.results().get(0);

using Xberg;

var config = new ExtractionConfig
{
    UseCache = true,
    EnableQualityProcessing = true
};

var result = (await XbergConverter.ExtractAsync(ExtractInput.FromUri("document.pdf"), config)).Results[0];
Console.WriteLine(result.Content);

require 'xberg'

config = Xberg::ExtractionConfig.new(
  use_cache: true,
  enable_quality_processing: true
)

input = Xberg::ExtractInput.new(uri: 'document.pdf')
result = Xberg.extract(input, config)

Configuration Files

Three formats are supported. TOML is recommended.

Xberg rejects unrecognized keys in its extraction configuration tables. A misspelled nested setting fails loading instead of being ignored; use the Configuration Reference for the authoritative wire names. Settings inside url.crawl follow crawlberg’s configuration schema.

use_cache = true
enable_quality_processing = true

[ocr]
backend = "tesseract"
language = "eng"

use_cache: true
enable_quality_processing: true

ocr:
  backend: tesseract
  language: eng

{
  "use_cache": true,
  "enable_quality_processing": true,
  "ocr": {
    "backend": "tesseract",
    "language": "eng"
  }
}

Automatic Discovery

When no --config path is supplied, Xberg walks up from the current working directory looking for xberg.toml and uses the first match. If no project-local file is found, it falls back to a per-user global config at xberg/xberg.{toml,yaml,yml,json} in the platform config directory — $XDG_CONFIG_HOME (or ~/.config) on Linux, ~/Library/Application Support on macOS, and %APPDATA% on Windows. In the project walk, YAML and JSON files are supported only when passed explicitly via --config. If nothing is found, defaults are used.

import asyncio
from xberg import ExtractInput, ExtractionConfig, extract

async def main() -> None:
    config: ExtractionConfig = ExtractionConfig()
    result = await extract(ExtractInput(uri="document.pdf"), config)

    content: str = result.results[0].content
    content_preview: str = content[:100]

    print(f"Content preview: {content_preview}")
    print(f"Total length: {len(content)}")

asyncio.run(main())

import { ExtractInputKind, extract, type ExtractionConfig } from "@xberg-io/xberg";

// Note: the Node binding has no config-file discovery helper. Build the
// config object directly (or load `xberg.toml`/`xberg.yaml`/`xberg.json`
// yourself and parse it) and pass it to `extract`.
const config: ExtractionConfig = {
  useCache: true,
};

const output = await extract({ kind: ExtractInputKind.Uri, uri: "document.pdf" }, config);
console.log(output.results?.[0]?.content);

use xberg::{extract, ExtractionConfig, ExtractInput};

#[tokio::main]
async fn main() -> xberg::Result<()> {
    let config = ExtractionConfig::discover()?.unwrap_or_default();
    let output = extract(ExtractInput::from_uri("document.pdf"), &config).await?;
    println!("{}", output.results[0].content);
    Ok(())
}

package main

import (
  "log"
  "os"
  "os/exec"
)

func main() {
  command := exec.Command("xberg", "extract", "document.pdf")
  command.Stdout = os.Stdout
  command.Stderr = os.Stderr
  if err := command.Run(); err != nil {
    log.Fatalf("extract with automatically discovered config: %v", err)
  }
}

import io.xberg.Xberg;
import io.xberg.ExtractInputKind;
import io.xberg.ExtractionResult;
import io.xberg.ExtractedDocument;
import io.xberg.ExtractionConfig;
import io.xberg.ExtractInput;

// Note: the Java binding has no config-file discovery helper. Build the
// config object directly (or load `xberg.toml`/`xberg.yaml`/`xberg.json`
// yourself and parse it) and pass it to `extract`.
ExtractionConfig config = ExtractionConfig.builder().build();
ExtractionResult output = Xberg.extract(
    ExtractInput.builder().withKind(ExtractInputKind.URI).withUri("document.pdf").build(),
    config
);
ExtractedDocument result = output.results().get(0);

using Xberg;

var config = new ExtractionConfig();
var result = (await XbergConverter.ExtractAsync(ExtractInput.FromUri("document.pdf"), config)).Results[0];

Console.WriteLine(result.Content[..Math.Min(100, result.Content.Length)]);
Console.WriteLine($"Total length: {result.Content.Length}");

require 'xberg'

config = Xberg::ExtractionConfig.discover
input = Xberg::ExtractInput.new(uri: 'document.pdf')
result = Xberg.extract(input, config)

import init, { extract } from "@xberg-io/xberg-wasm";

await init();

const config = {
  use_cache: true,
  enable_quality_processing: true,
  ocr: {
    backend: "tesseract",
    language: ["eng"],
  },
};

const buffer = await fetch("document.pdf").then((response) => response.arrayBuffer());
const bytes = new Uint8Array(buffer);
const result = await extract({ kind: "bytes", bytes, mimeType: "application/pdf" }, config);
console.log(result.results[0].content);

Automatic discovery is a CLI and server feature. The Node binding has no discovery helper, so read the file yourself and pass the parsed object as config:

/// <reference types="node" />
import { existsSync, readFileSync } from "node:fs";
import { ExtractInputKind, extract, type ExtractionConfig } from "@xberg-io/xberg";

const input = {
  kind: ExtractInputKind.Uri,
  uri: "document.pdf",
};

const configPath = "xberg.json";

if (existsSync(configPath)) {
  console.log("Found configuration file");
  const config = JSON.parse(readFileSync(configPath, "utf8")) as ExtractionConfig;
  const output = await extract(input, config);
  console.log(output.results?.[0]?.content);
} else {
  console.log("No configuration file found, using defaults");
  const output = await extract(input);
  console.log(output.results?.[0]?.content);
}

Environment Variable Overrides

ExtractionConfig::apply_env_overrides() applies XBERG_* variables on top of an already-loaded config. Each variable that is set overrides the matching config-file value; unset variables are ignored. The serve and mcp commands call it automatically after loading the config. The extract and batch commands do not apply it — use flags or --config-json there.

Variable	Overrides
`XBERG_OCR_LANGUAGE`	OCR language (ISO 639 code, e.g. `eng`, `deu`)
`XBERG_OCR_BACKEND`	OCR backend (`tesseract`, `paddle-ocr`, `sceptre`, `vlm`)
`XBERG_DISABLE_OCR`	Disable OCR entirely (`true`/`false`)
`XBERG_CHUNKING_MAX_CHARS`	Maximum characters per chunk
`XBERG_CHUNKING_MAX_OVERLAP`	Overlap between chunks
`XBERG_CHUNKING_TOKENIZER`	HuggingFace tokenizer model ID for token-based sizing
`XBERG_CACHE_ENABLED`	Cache flag (`true`/`false`)
`XBERG_TOKEN_REDUCTION_MODE`	Token reduction level (`off`, `light`, `moderate`, `aggressive`, `maximum`)
`XBERG_OUTPUT_FORMAT`	Output format
`XBERG_LAYOUT_PRESET`	Layout detection preset (`fast`, `accurate`)
`XBERG_LLM_MODEL`	LLM model for structured extraction
`XBERG_LLM_API_KEY`	API key for the structured-extraction LLM provider
`XBERG_LLM_BASE_URL`	Custom base URL for the LLM provider
`XBERG_VLM_OCR_MODEL`	VLM model for vision-based OCR
`XBERG_VLM_EMBEDDING_MODEL`	LLM model for embedding generation
`XBERG_EMBEDDING_PLUGIN_NAME`	Name of a registered in-process embedding backend

Server-only variables (XBERG_HOST, XBERG_PORT, XBERG_CORS_ORIGINS, XBERG_MAX_REQUEST_BODY_BYTES, XBERG_MAX_MULTIPART_FIELD_BYTES) configure the API/MCP server, not extraction.

Loading Precedence

For the extract and batch commands, sources are applied highest to lowest:

Individual CLI flags (--ocr, --output-format, --chunk, …)
Inline JSON (--config-json or --config-json-base64) — merged field by field, not whole-object
Config file — explicit --config, otherwise the auto-discovered xberg.toml
Built-in defaults

The serve and mcp commands add environment variables on top of the loaded config via apply_env_overrides(), so a set XBERG_* variable overrides the config-file value in those modes.

Common Use Cases

Cache and Quality Processing

Two flags carry most of the cost and quality trade-off. use_cache reuses the result of an earlier extraction of the same input. enable_quality_processing cleans up the extracted text before it is returned:

import asyncio
from xberg import ExtractInput, extract, ExtractionConfig

async def main() -> None:
    config = ExtractionConfig(
        use_cache=True,
        enable_quality_processing=True
    )
    result = await extract(ExtractInput(uri="document.pdf"), config)
    print(result.results[0].content)

asyncio.run(main())

import { ExtractInputKind, extract } from "@xberg-io/xberg";

const config = {
  useCache: true,
  enableQualityProcessing: true,
};

const output = await extract(
  {
    kind: ExtractInputKind.Uri,
    uri: "document.pdf",
  },
  config,
);

console.log(output.results?.[0]?.content);
console.log(`MIME Type: ${output.results?.[0]?.mimeType}`);

use xberg::{extract, ExtractionConfig, ExtractInput};

#[tokio::main]
async fn main() -> xberg::Result<()> {
    let config = ExtractionConfig {
        use_cache: true,
        enable_quality_processing: true,
        ..Default::default()
    };

    let output = extract(ExtractInput::from_uri("document.pdf"), &config).await?;
    println!("{}", output.results[0].content);
    println!("MIME Type: {}", output.results[0].mime_type);
    Ok(())
}

Setting Up OCR

import asyncio
from xberg import ExtractInput, ExtractionConfig, OcrConfig, TesseractConfig, extract

async def main() -> None:
    config: ExtractionConfig = ExtractionConfig(
        ocr=OcrConfig(
            backend="tesseract", language="eng+fra",
            tesseract_config=TesseractConfig(psm=3)
        )
    )
    result = await extract(ExtractInput(uri="document.pdf"), config)
    print(result.results[0].content)

asyncio.run(main())

import { ExtractInputKind, extract } from "@xberg-io/xberg";

const config = {
  ocr: {
    backend: "tesseract",
    language: ["eng", "fra"],
    tesseractConfig: {
      psm: 3,
    },
  },
};

const output = await extract(
  {
    kind: ExtractInputKind.Uri,
    uri: "document.pdf",
  },
  config,
);

console.log(output.results?.[0]?.content);

use xberg::{ExtractionConfig, OcrConfig, TesseractConfig};

fn main() {
    let config = ExtractionConfig {
        ocr: Some(OcrConfig {
            backend: "tesseract".to_string(),
            language: vec!["eng".to_string(), "fra".to_string()],
            tesseract_config: Some(TesseractConfig {
                psm: Some(3),
                ..Default::default()
            }),
            ..Default::default()
        }),
        ..Default::default()
    };
}

package main

import "github.com/xberg-io/xberg/packages/go"

func main() {
  psm := int32(3)

  _ = xberg.ExtractionConfig{
    Ocr: &xberg.OcrConfig{
      Backend:  xberg.Ptr("tesseract"),
      Language: []string{"eng", "fra"},
      TesseractConfig: &xberg.TesseractConfig{
        Psm: &psm,
      },
    },
  }
}

import io.xberg.ExtractionConfig;
import io.xberg.OcrConfig;
import io.xberg.TesseractConfig;
import java.util.List;

ExtractionConfig config = ExtractionConfig.builder()
    .withOcr(OcrConfig.builder()
        .withBackend("tesseract")
        .withLanguage(List.of("eng", "fra"))
        .withTesseractConfig(TesseractConfig.builder()
            .withPsm(3)
            .build())
        .build())
    .build();

using Xberg;

var config = new ExtractionConfig
{
    Ocr = new OcrConfig
    {
        Backend = "tesseract",
        Language = new List<string> { "eng", "fra" },
        TesseractConfig = new TesseractConfig { Psm = 3 }
    }
};

var result = (await XbergConverter.ExtractAsync(ExtractInput.FromUri("document.pdf"), config)).Results[0];
Console.WriteLine(result.Content);

require 'xberg'

config = Xberg::ExtractionConfig.new(
  ocr: Xberg::OcrConfig.new(
    backend: 'tesseract',
    language: 'eng+fra',
    tesseract_config: Xberg::TesseractConfig.new(psm: 3)
  )
)

For backend selection and language packs, see OCR Guide. For fine-grained Tesseract tuning, see TesseractConfig Reference.

For Sceptre, use the backend name sceptre and place its sections directly in backend_options:

[ocr]
backend = "sceptre"
language = ["eng", "deu"]

[ocr.backend_options.recognition]
batch_size = 4

[ocr.backend_options.concurrency]
max_threads = 2

Do not nest these options under backend_options.sceptre. Custom Rust builds use sceptre-ocr for the ONNX Runtime desktop/server backend or sceptre-ocr-tract for Android and iOS. WebAssembly support uses the opt-in Sceptre worker build/API because the model and tract runtime size are not part of the default wasm-target bundle. Use ocr.language for language selection; it overrides backend_options.model.languages. Leave backend_options.model.backend unset so Xberg can select ORT or tract for the target. The supported option paths are backend_options.detection.*, backend_options.recognition.*, backend_options.concurrency.max_threads, backend_options.model.cache_dir, backend_options.model.registry_owner, backend_options.model.detector_path, and backend_options.model.recognizer_path. cache_dir and automatic model download apply only to desktop/server ORT builds. Android and iOS exclude the downloader; both model paths are required and must reference application-resolved bundle or asset files.

Chunking for RAG

from xberg import (
    ExtractionConfig,
    ChunkingConfig,
    EmbeddingConfig,
    EmbeddingModelType,
)

config: ExtractionConfig = ExtractionConfig(
    chunking=ChunkingConfig(
        max_characters=1500,
        overlap=200,
        embedding=EmbeddingConfig(
            model=EmbeddingModelType.preset("balanced")
        ),
    )
)

import { ExtractInputKind, extract, type ExtractionConfig } from "@xberg-io/xberg";

const config: ExtractionConfig = {
  chunking: {
    maxCharacters: 1500,
    overlap: 200,
    embedding: {
      model: { type: "preset", name: "quality" },
    },
  },
};

const output = await extract({ kind: ExtractInputKind.Uri, uri: "document.pdf" }, config);
console.log(`Chunks created: ${output.results?.[0]?.chunks?.length ?? 0}`);

use xberg::{ChunkingConfig, EmbeddingConfig, EmbeddingModelType, ExtractionConfig};

fn main() {
    let config = ExtractionConfig {
        chunking: Some(ChunkingConfig {
            max_characters: 1500,
            overlap: 200,
            embedding: Some(EmbeddingConfig {
                model: EmbeddingModelType::Preset {
                    name: "text-embedding-all-minilm-l6-v2".to_string(),
                },
                ..Default::default()
            }),
            ..Default::default()
        }),
        ..Default::default()
    };
    println!("{:?}", config.chunking);
}

package main

import (
  "fmt"
  "log"

  "github.com/xberg-io/xberg/packages/go"
)

func main() {
  maxChars := uint(1000)
  overlap := uint(200)
  cfg := xberg.ExtractionConfig{
    Chunking: &xberg.ChunkingConfig{
      MaxCharacters: &maxChars,
      Overlap:       &overlap,
    },
  }

  input := xberg.ExtractInputFromURI("document.pdf")
  result, err := xberg.Extract(*input, cfg)
  if err != nil {
    log.Fatalf("extract failed: %v", err)
  }

  for i, chunk := range result.Results[0].Chunks {
    // Byte offsets (UTF-8 valid boundaries) into the original document text.
    fmt.Printf("Chunk %d/%d (%d-%d)\n", i+1, chunk.Metadata.TotalChunks, chunk.Metadata.ByteStart, chunk.Metadata.ByteEnd)
    fmt.Printf("%s...\n", chunk.Content[:min(len(chunk.Content), 100)])
  }
}

func min(a, b int) int {
  if a < b {
    return a
  }
  return b
}

import io.xberg.ChunkingConfig;
import io.xberg.EmbeddingConfig;
import io.xberg.EmbeddingModelType;
import io.xberg.ExtractionConfig;

ExtractionConfig config = ExtractionConfig.builder()
    .withChunking(ChunkingConfig.builder()
        .withMaxCharacters(1500L)
        .withOverlap(200L)
        .withEmbedding(EmbeddingConfig.builder()
            .withModel(new EmbeddingModelType.Preset("text-embedding-all-minilm-l6-v2"))
            .build())
        .build())
    .build();

using Xberg;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

var config = new ExtractionConfig
{
    Chunking = new ChunkingConfig
    {
        MaxCharacters = 512,
        Overlap = 50,
        Embedding = new EmbeddingConfig
        {
            Model = new EmbeddingModelType.Preset("balanced"),
            Normalize = true,
            BatchSize = 32,
            ShowDownloadProgress = false
        }
    }
};

var result = (await XbergConverter.ExtractAsync(ExtractInput.FromUri("document.pdf"), config)).Results[0];

var chunks = result.Chunks ?? new List<Chunk>();
foreach (var (index, chunk) in chunks.WithIndex())
{
    var chunkId = $"doc_chunk_{index}";
    Console.WriteLine($"Chunk {chunkId}: {chunk.Content[..Math.Min(50, chunk.Content.Length)]}");

    if (chunk.Embedding != null)
    {
        Console.WriteLine($"  Embedding dimensions: {chunk.Embedding.Count}");
    }
}

internal static class EnumerableExtensions
{
    public static IEnumerable<(int Index, T Item)> WithIndex<T>(
        this IEnumerable<T> items)
    {
        var index = 0;
        foreach (var item in items)
        {
            yield return (index++, item);
        }
    }
}

require 'xberg'

config = Xberg::ExtractionConfig.new(
  chunking: Xberg::ChunkingConfig.new(
    max_characters: 1500,
    overlap: 200,
    embedding: Xberg::EmbeddingConfig.new(
      model: Xberg::EmbeddingModelType.new(
        type: 'preset',
        name: 'text-embedding-all-minilm-l6-v2'
      )
    )
  )
)

Concurrency and Thread Limits

ConcurrencyConfig.max_threads caps every internal thread pool at once: the global Rayon pool, ONNX Runtime intra-op threads, and the combined document/worker budget used by batch extraction.

When max_threads is left unset, the effective budget is min(detected_cpu_cores, 8) — not “use all available cores”. This 8-core ceiling is a deliberate serverless/shared-tenant default, not an auto-scaling target. On a host with more than 8 cores, the extra cores go unused by default:

Bare metal / VM with no CPU quota: max_threads must be set explicitly above 8 to use more than 8 cores. There is no other way to exceed the default ceiling on this class of host.
Linux containers under a cgroup CPU quota (e.g. Kubernetes resources.limits.cpu): the quota is used as the ceiling instead of the hardcoded 8, since the quota already reflects a deliberately-configured resource limit. This applies automatically; no configuration is needed.

If none of the above applies and the host has more than 8 cores, a one-time WARN-level log is emitted the first time the thread budget is resolved, naming the detected core count and the applied cap — so the ceiling is discoverable without reading source.

[concurrency]
max_threads = 32

ConcurrencyConfig.max_concurrent_ocr limits concurrent Tesseract recognition sessions on its own. When it is unset, recognition follows the thread budget, reduced to the number of sessions the host’s free memory holds. Set it when the host has cores to spare but not the memory to run a recognition session on each of them. The value is applied as given: neither max_threads nor the free-memory reading reduces it. The first extraction in a process fixes it for the rest of that process, and a later extraction that names a different value keeps the first one and logs a one-time WARN. See Concurrency & Scaling.

[concurrency]
max_threads = 32
max_concurrent_ocr = 8

All Configuration Categories

ExtractionConfig — top-level options
OcrConfig — OCR backend, language, acceleration
TesseractConfig — Tesseract PSM, confidence, table detection
ChunkingConfig — chunk size, overlap
TokenReductionConfig — LLM prompt token reduction
ContentFilterConfig — header/footer/watermark filtering
PageConfig — page tracking and markers
AccelerationConfig — ONNX Runtime execution provider
ConcurrencyConfig — thread pool caps (max_threads) and the recognition session limit (max_concurrent_ocr); not in the auto-generated reference below, see the section above

Next Steps

Extraction Basics — core extraction API and supported formats
OCR Guide — backend installation and language setup
Embeddings — semantic vectors for search
Language Detection — multilingual document analysis
Chunking — split text for RAG with page tracking
Plugins Guide — custom post-processors and validators