Omni.Tools.WebSearch.Provider behaviour (Omni Tools v0.3.0)

Copy Markdown View Source

Behaviour for web search providers.

A provider implements a single callback — search/2 — that executes a web search query and returns a list of results.

Example

defmodule MyApp.BraveProvider do
  @behaviour Omni.Tools.WebSearch.Provider

  @impl true
  def search(query, opts) do
    api_key = Keyword.fetch!(opts, :api_key)
    # ... HTTP request to Brave Search API ...
    {:ok, [%{url: "...", title: "...", snippet: "..."}]}
  end
end

Usage

Pass your provider to Omni.Tools.WebSearch.new/1:

Omni.Tools.WebSearch.new(
  provider: {MyApp.BraveProvider, api_key: "..."}
)

Summary

Types

result()

A single search result.

Callbacks

search(query, opts)

Executes a web search query.

Functions

validate!(mod)

Validates a provider spec as a {module, opts} tuple.

Types

result()

@type result() :: %{url: String.t(), title: String.t(), snippet: String.t()}

A single search result.

Callbacks

search(query, opts)

@callback search(query :: String.t(), opts :: keyword()) ::
  {:ok, [result()]} | {:error, term()}

Executes a web search query.

Receives the query string and a keyword list of options (provider config merged with runtime parameters like :num_results and :recency). Returns {:ok, results} on success or {:error, reason} on failure.

Functions

validate!(mod)

@spec validate!(module() | {module(), keyword()}) :: {module(), keyword()}

Validates a provider spec as a {module, opts} tuple.

Accepts a bare module (treated as {module, []}) or a {module, opts} tuple. Raises ArgumentError if the module cannot be loaded or does not export search/2.

Provider.validate!({MyProvider, api_key: "..."})
#=> {MyProvider, [api_key: "..."]}

Provider.validate!(MyProvider)
#=> {MyProvider, []}