Behaviour for search execution in the Agent pipeline.

The searcher retrieves relevant chunks from a knowledge base based on the query. This allows swapping Arcana's built-in pgvector search for any search backend.

Built-in Implementations

• Arcana.Agent.Searcher.Arcana - Uses Arcana's pgvector search (default)

Implementing a Custom Searcher

defmodule MyApp.ElasticsearchSearcher do
  @behaviour Arcana.Agent.Searcher

  @impl true
  def search(question, collection, opts) do
    limit = Keyword.get(opts, :limit, 5)

    # Your Elasticsearch query
    case Elasticsearch.search(collection, question, limit: limit) do
      {:ok, hits} ->
        chunks = Enum.map(hits, &to_chunk/1)
        {:ok, chunks}
      {:error, reason} ->
        {:error, reason}
    end
  end

  defp to_chunk(hit) do
    %{
      id: hit["_id"],
      text: hit["_source"]["content"],
      metadata: hit["_source"]["metadata"],
      similarity: hit["_score"]
    }
  end
end

Using a Custom Searcher

Agent.new(question, repo: repo, llm: llm)
|> Agent.search(searcher: MyApp.ElasticsearchSearcher)
|> Agent.answer()

Using an Inline Function

Agent.search(ctx,
  searcher: fn question, collection, opts ->
    {:ok, my_search(question, collection, opts)}
  end
)

Chunk Format

The searcher must return chunks as maps with at least these fields:

• :id - Unique identifier for the chunk
• :text - The text content
• :metadata - Optional metadata map
• :similarity - Optional similarity score (0.0-1.0)