Annotates documents with extractions using LLMs.

The core extraction orchestrator that:

1. Chunks documents
2. Generates prompts
3. Calls LLM via ReqLLM
4. Parses and aligns results
5. Aggregates into AnnotatedDocument

Extraction Modes

The Annotator supports two modes of operation:

Text Generation Mode (Default)

Uses ReqLLM.generate_text/3 to generate free-form text responses in JSON or YAML format. The LLM response is parsed and converted to extractions.

template = %{
  description: "Extract medication entities",
  examples: [
    %{
      text: "Patient takes aspirin 100mg",
      extractions: [
        %{extraction_class: "Medication", name: "aspirin", dosage: "100mg"}
      ]
    }
  ]
}

annotator = LeXtract.Annotator.new(template,
  model: "gemini-2.0-flash",
  provider: :gemini,
  api_key: "your-api-key"
)

doc = LeXtract.Annotator.annotate_text(annotator, "Patient takes aspirin 100mg daily")

Structured Output Mode

Uses ReqLLM.generate_object/4 to generate structured output with schema validation. This mode automatically generates a schema from your examples and ensures the LLM response conforms to the expected structure.

Enable with :use_structured_output option:

template = %{
  description: "Extract medication entities with structured output",
  examples: [
    %{
      text: "Patient takes aspirin 100mg twice daily",
      extractions: [
        %{
          extraction_class: "Medication",
          name: "aspirin",
          dosage: "100mg",
          frequency: "twice daily"
        }
      ]
    }
  ]
}

annotator = LeXtract.Annotator.new(template,
  [model: "gemini-2.0-flash", provider: :gemini, api_key: "your-api-key"],
  use_structured_output: true
)

doc = LeXtract.Annotator.annotate_text(annotator, "Patient takes aspirin 100mg twice daily")

Structured output mode offers several benefits:

• Automatic schema generation from examples
• Built-in validation by the LLM provider
• More reliable parsing (no JSON/YAML parsing errors)
• Better support for complex nested structures

Examples

iex> template = %{
...>   description: "Extract medication entities",
...>   examples: [
...>     %{
...>       text: "Patient takes aspirin",
...>       extractions: [%{medication: "aspirin"}]
...>     }
...>   ]
...> }
iex> annotator = LeXtract.Annotator.new(template,
...>   model: "gemini-2.0-flash",
...>   provider: :gemini,
...>   api_key: "test-key"
...> )
iex> is_struct(annotator, LeXtract.Annotator)
true