@spec discover() :: {:ok, t()} | {:error, :not_found | String.t()}

Discover and load an ExtractionConfig by searching directories.

Searches the current working directory and all parent directories for a configuration file in the following order:

1. kreuzberg.toml
2. kreuzberg.yaml
3. kreuzberg.yml
4. kreuzberg.json

Returns the first configuration file found.

Returns

• {:ok, config} - Successfully discovered and loaded configuration
• {:error, :not_found} - No configuration file found in directory tree
• {:error, reason} - Error loading or parsing the configuration file

Examples

# With kreuzberg.toml in current directory
iex> Kreuzberg.ExtractionConfig.discover()
{:ok, %Kreuzberg.ExtractionConfig{...}}

# With kreuzberg.yaml in a parent directory
iex> Kreuzberg.ExtractionConfig.discover()
{:ok, config}

# When no config file exists
iex> Kreuzberg.ExtractionConfig.discover()
{:error, :not_found}

@spec from_file(String.t() | Path.t()) :: {:ok, t()} | {:error, String.t()}

Load an ExtractionConfig from a file.

Supports TOML, YAML, and JSON configuration file formats. The file format is automatically detected based on the file extension or file contents.

Parameters

• file_path - Path to the configuration file (String or Path.t())

Returns

• {:ok, config} - Successfully loaded configuration as a struct
• {:error, reason} - Failed to load or parse the configuration file

Supported Formats

• .toml - TOML format (e.g., kreuzberg.toml)
• .yaml, .yml - YAML format (e.g., kreuzberg.yaml)
• .json - JSON format (e.g., kreuzberg.json)

Examples

iex> Kreuzberg.ExtractionConfig.from_file("kreuzberg.toml")
{:ok, %Kreuzberg.ExtractionConfig{...}}

iex> Kreuzberg.ExtractionConfig.from_file("/etc/config/extraction.yaml")
{:ok, config}

iex> Kreuzberg.ExtractionConfig.from_file("/nonexistent/file.toml")
{:error, "File not found: /nonexistent/file.toml"}

@spec to_map(t() | map() | nil | list()) :: map() | nil

Converts an ExtractionConfig struct to a map for NIF serialization.

Returns a map containing all configuration fields, both boolean flags and nested configurations. Serializes all values including nil for complete representation.

Parameters

• config - An ExtractionConfig struct, a plain map, nil, or a keyword list

Returns

A map with string keys representing the configuration options. All fields are included, allowing the Rust side to override with provided values.

Field Descriptions

• "chunking" - Text chunking configuration (map or nil)
• "ocr" - OCR backend configuration (map or nil)
• "language_detection" - Language detection settings (map or nil)
• "postprocessor" - Post-processor configuration (map or nil)
• "images" - Image extraction configuration (map or nil)
• "pages" - Page-level extraction configuration (map or nil)
• "token_reduction" - Token reduction settings (map or nil)
• "keywords" - Keyword extraction configuration (map or nil)
• "pdf_options" - PDF-specific options (map or nil)
• "use_cache" - Enable caching (boolean)
• "enable_quality_processing" - Enable quality processing (boolean)
• "force_ocr" - Force OCR usage (boolean)

Examples

iex> config = %Kreuzberg.ExtractionConfig{chunking: %{"size" => 512}}
iex> Kreuzberg.ExtractionConfig.to_map(config)
%{
  "chunking" => %{"size" => 512},
  "ocr" => nil,
  "language_detection" => nil,
  "postprocessor" => nil,
  "images" => nil,
  "pages" => nil,
  "token_reduction" => nil,
  "keywords" => nil,
  "pdf_options" => nil,
  "use_cache" => true,
  "enable_quality_processing" => true,
  "force_ocr" => false
}

iex> config = %Kreuzberg.ExtractionConfig{}
iex> Kreuzberg.ExtractionConfig.to_map(config)
%{
  "chunking" => nil,
  "ocr" => nil,
  "language_detection" => nil,
  "postprocessor" => nil,
  "images" => nil,
  "pages" => nil,
  "token_reduction" => nil,
  "keywords" => nil,
  "pdf_options" => nil,
  "use_cache" => true,
  "enable_quality_processing" => true,
  "force_ocr" => false
}

iex> Kreuzberg.ExtractionConfig.to_map(nil)
nil

iex> Kreuzberg.ExtractionConfig.to_map(%{"use_cache" => false})
%{"use_cache" => false}

@spec validate(t()) :: {:ok, t()} | {:error, String.t()}

Validates an ExtractionConfig for correct field types and values.

Ensures that:

• Boolean fields (use_cache, enable_quality_processing, force_ocr) are actually booleans
• Nested configuration fields are maps or nil
• All values are valid according to the configuration schema

This function is useful for early validation before passing configuration to the extraction functions.

Parameters

• config - An ExtractionConfig struct to validate

Returns

• {:ok, config} - If the configuration is valid
• {:error, reason} - If validation fails, with a descriptive error message

Examples

iex> config = %Kreuzberg.ExtractionConfig{use_cache: true}
iex> Kreuzberg.ExtractionConfig.validate(config)
{:ok, config}

iex> config = %Kreuzberg.ExtractionConfig{chunking: %{"size" => 1024}}
iex> Kreuzberg.ExtractionConfig.validate(config)
{:ok, config}

iex> config = %Kreuzberg.ExtractionConfig{use_cache: "yes"}
iex> Kreuzberg.ExtractionConfig.validate(config)
{:error, "Field 'use_cache' must be a boolean, got: string"}

iex> config = %Kreuzberg.ExtractionConfig{chunking: "invalid"}
iex> Kreuzberg.ExtractionConfig.validate(config)
{:error, "Field 'chunking' must be a map or nil, got: string"}

iex> config = %Kreuzberg.ExtractionConfig{force_ocr: true, enable_quality_processing: true}
iex> Kreuzberg.ExtractionConfig.validate(config)
{:ok, config}