# `LeXtract.Config`
[🔗](https://github.com/YgorCastor/lextract.git/blob/main/lib/lextract/config.ex#L1)

Configuration for extraction operations using NimbleOptions for validation.

## Examples

    iex> config = LeXtract.Config.new(prompt: "test", max_char_buffer: 2000)
    iex> config.max_char_buffer
    2000

    iex> config = LeXtract.Config.default()
    iex> config.batch_size
    5

# `options`

```elixir
@type options() :: [
  prompt: binary(),
  examples: [term()],
  template_file: binary(),
  format: term(),
  fence_output: boolean(),
  use_structured_output: boolean(),
  max_char_buffer: pos_integer(),
  chunk_overlap: non_neg_integer(),
  batch_size: pos_integer(),
  extraction_passes: pos_integer(),
  max_concurrency: pos_integer(),
  attribute_suffix: binary()
]
```

* `:prompt` (`t:String.t/0`) - Extraction prompt/description

* `:examples` (list of `t:term/0`) - List of example extractions (maps with :text and :extractions keys) The default value is `[]`.

* `:template_file` (`t:String.t/0`) - Path to template file (.json or .yaml)

* `:format` - Output format for extractions The default value is `:yaml`.

* `:fence_output` (`t:boolean/0`) - Expect fenced code blocks in LLM response The default value is `false`.

* `:use_structured_output` (`t:boolean/0`) - Use structured output mode (generate_object) The default value is `false`.

* `:max_char_buffer` (`t:pos_integer/0`) - Maximum chunk size in characters The default value is `1000`.

* `:chunk_overlap` (`t:non_neg_integer/0`) - Character overlap between chunks (default: 20% of max_char_buffer)

* `:batch_size` (`t:pos_integer/0`) - Number of chunks per LLM batch The default value is `5`.

* `:extraction_passes` (`t:pos_integer/0`) - Number of extraction passes for multi-pass extraction The default value is `1`.

* `:max_concurrency` (`t:pos_integer/0`) - Maximum concurrent LLM requests The default value is `8`.

* `:attribute_suffix` (`t:String.t/0`) - Suffix for attribute keys in structured output The default value is `"_attributes"`.

# `t`

```elixir
@type t() :: %LeXtract.Config{
  attribute_suffix: String.t(),
  batch_size: pos_integer(),
  chunk_overlap: non_neg_integer(),
  examples: [map()],
  extraction_passes: pos_integer(),
  fence_output: boolean(),
  format: :json | :yaml,
  max_char_buffer: pos_integer(),
  max_concurrency: pos_integer(),
  prompt: String.t() | nil,
  template_file: String.t() | nil,
  use_structured_output: boolean()
}
```

# `default`

```elixir
@spec default() :: t()
```

Returns default configuration.

## Examples

    iex> config = LeXtract.Config.default()
    iex> config.batch_size
    5

# `from_keyword`

```elixir
@spec from_keyword(keyword()) :: {:ok, t()} | {:error, Exception.t()}
```

Converts a keyword list to a Config struct with validation.

This function is useful for maintaining backward compatibility with
code that uses keyword lists. It validates the options and returns
a Config struct.

## Examples

    iex> {:ok, config} = LeXtract.Config.from_keyword(prompt: "test")
    iex> config.prompt
    "test"

    iex> {:error, _} = LeXtract.Config.from_keyword([])

# `from_keyword!`

```elixir
@spec from_keyword!(keyword()) :: t()
```

Converts a keyword list to a Config struct, raising on error.

## Examples

    iex> config = LeXtract.Config.from_keyword!(prompt: "test")
    iex> config.prompt
    "test"

# `new`

```elixir
@spec new(keyword()) :: t()
```

Creates and validates configuration from keyword list.

Validates options using NimbleOptions and raises `NimbleOptions.ValidationError` if invalid.

## Examples

    iex> config = LeXtract.Config.new(prompt: "test", max_char_buffer: 2000)
    iex> config.max_char_buffer
    2000

    iex> LeXtract.Config.new(prompt: "test", max_char_buffer: -1)
    ** (NimbleOptions.ValidationError) invalid value for :max_char_buffer option: expected positive integer, got: -1

    iex> LeXtract.Config.new(prompt: "test", format: :xml)
    ** (NimbleOptions.ValidationError) invalid value for :format option: expected one of [:json, :yaml], got: :xml

# `to_keyword`

```elixir
@spec to_keyword(t()) :: keyword()
```

Converts a Config struct to a keyword list.

This is useful for backward compatibility when functions expect keyword lists.

## Examples

    iex> config = LeXtract.Config.new(prompt: "test")
    iex> kw = LeXtract.Config.to_keyword(config)
    iex> Keyword.get(kw, :prompt)
    "test"

# `validate`

```elixir
@spec validate(keyword() | t()) :: {:ok, t()} | {:error, Exception.t()}
```

Validates configuration keyword list or struct.

Returns `{:ok, validated_config}` on success or `{:error, validation_error}` on failure.

## Examples

    iex> {:ok, config} = LeXtract.Config.validate(max_char_buffer: 1000, prompt: "test")
    iex> config.max_char_buffer
    1000

    iex> {:error, error} = LeXtract.Config.validate(max_char_buffer: -1, prompt: "test")
    iex> String.contains?(Exception.message(error), "expected positive integer")
    true

    iex> {:error, error} = LeXtract.Config.validate(format: :xml, prompt: "test")
    iex> String.contains?(Exception.message(error), "expected one of")
    true

# `validate!`

```elixir
@spec validate!(keyword() | t()) :: t()
```

Validates configuration and raises on error.

Returns the validated config struct or raises `LeXtract.Error.Invalid.Config`.

## Examples

    iex> LeXtract.Config.validate!(max_char_buffer: 1000, prompt: "test")
    %LeXtract.Config{max_char_buffer: 1000, prompt: "test"}

    iex> LeXtract.Config.validate!(max_char_buffer: -1, prompt: "test")
    ** (LeXtract.Error.Invalid.Config) Configuration validation failed: invalid value for :max_char_buffer option: expected positive integer, got: -1

---

*Consult [api-reference.md](api-reference.md) for complete listing*