Nous.Tools.Search.Common (nous v0.17.0)

Shared plumbing for search tools (Brave, Tavily, ...).

Owns the pieces every search tool repeats: API-key resolution, query extraction, the success/error result envelope, and response-to-result field mapping.

Summary

Functions

api_key(ctx, key, env_var)

Resolve an API key: context deps first, then application config under :nous, then the system environment.

map_results(results, fields)

Map raw API result maps to the tool's result shape.

query(args)

Extract the query from tool args, accepting "query" or "q".

run_search(query, api_key, opts, fun)

Run a search behind the standard result envelope.

Functions

api_key(ctx, key, env_var)

@spec api_key(Nous.RunContext.t(), atom(), String.t()) :: String.t() | nil

Resolve an API key: context deps first, then application config under :nous, then the system environment.

map_results(results, fields)

@spec map_results(
  term(),
  keyword()
) :: [map()]

Map raw API result maps to the tool's result shape.

fields is a keyword list of output_key: "source_key" or output_key: {"source_key", default}. Non-list input yields [] so a malformed response can't crash the tool.

query(args)

@spec query(map()) :: String.t()

Extract the query from tool args, accepting "query" or "q".

run_search(query, api_key, opts, fun)

@spec run_search(String.t(), String.t() | nil, keyword(), (-> {:ok, map()}
                                                        | {:error, term()})) ::
  map()

Run a search behind the standard result envelope.

When api_key is missing or empty, returns the failure envelope with opts[:missing_key_error] without invoking fun. Otherwise fun must return {:ok, envelope_map} (merged with query and success: true) or {:error, reason} (logged under opts[:log_label], wrapped with opts[:error_prefix]).