Arcana.Graph.GraphExtractor behaviour (Arcana v2.0.1)

Copy Markdown View Source

Behaviour for combined entity and relationship extraction in GraphRAG.

A GraphExtractor extracts both entities and relationships in a single pass, which is more efficient than separate extractors when using LLMs.

Built-in Implementations

Configuration

Configure your graph extractor in config.exs:

# Combined extractor (efficient, 1 LLM call per chunk):
config :arcana, :graph,
  extractor: Arcana.Graph.GraphExtractor.LLM

# Or configure separately (flexible, 2 LLM calls per chunk):
config :arcana, :graph,
  entity_extractor: Arcana.Graph.EntityExtractor.NER,
  relationship_extractor: Arcana.Graph.RelationshipExtractor.LLM

When extractor is set, it takes priority over separate extractors.

Implementing a Custom Extractor

Create a module that implements this behaviour:

defmodule MyApp.CustomExtractor do
  @behaviour Arcana.Graph.GraphExtractor

  @impl true
  def extract(text, opts) do
    # Extract entities and relationships together
    entities = [%{name: "Entity", type: :concept}]
    relationships = [%{source: "A", target: "B", type: "RELATED"}]
    {:ok, %{entities: entities, relationships: relationships}}
  end
end

Output Format

Extractors must return a map with:

  • :entities - List of entity maps with :name, :type, and optional :description
  • :relationships - List of relationship maps with :source, :target, :type, and optional :description and :strength

Summary

Callbacks

extract(text, opts)

Extracts entities and relationships from text in a single pass.

Functions

extract(fun, text)

Extracts graph data using the configured extractor.

Callbacks

extract(text, opts)

@callback extract(text :: String.t(), opts :: keyword()) ::
  {:ok, map()} | {:error, term()}

Extracts entities and relationships from text in a single pass.

Parameters

  • text - The source text to analyze
  • opts - Options passed from the extractor configuration

Returns

  • {:ok, %{entities: [...], relationships: [...]}} - Extracted graph data
  • {:error, reason} - On failure

Functions

extract(fun, text)

Extracts graph data using the configured extractor.

The extractor can be:

  • A {module, opts} tuple where module implements this behaviour

  • A function (text, opts) -> {:ok, result} | {:error, reason}

  • nil to skip extraction (returns empty result)

Examples

# With module
extractor = {Arcana.Graph.GraphExtractor.LLM, llm: my_llm}
{:ok, result} = GraphExtractor.extract(extractor, text)

# With inline function
extractor = fn text, _opts ->
  {:ok, %{entities: [], relationships: []}}
end
{:ok, result} = GraphExtractor.extract(extractor, text)