tools.brave_search module

Web search via the Brave Search API with rate limiting and key rotation.

class tools.brave_search.BraveAPIKeyManager[source]

Bases: object

Round-robin API key manager with automatic rotation.

__init__()[source]: Initialize the instance.

load_keys(config)[source]

Load keys from the configured source.

Parameters:: config – Bot configuration object.

async get_next_key()[source]

Retrieve the next key.

Returns:: The result.
Return type:: Optional[str]

rotate_key()[source]

Rotate key.

Returns:: The result.
Return type:: Optional[str]

get_current_key()[source]

Retrieve the current key.

Returns:: The result.
Return type:: Optional[str]

get_key_count()[source]

Retrieve the key count.

Returns:: The result.
Return type:: int

class tools.brave_search.BraveSearchTask(query, count, country, search_lang, ui_lang, safesearch, future, user_api_key=None, user_id=None, redis_client=None)[source]

Bases: object

BraveSearchTask.

Parameters:

query (str)
count (int | None)
country (str | None)
search_lang (str | None)
ui_lang (str | None)
safesearch (str | None)
future (Future)
user_api_key (str | None)
user_id (str | None)
redis_client (object | None)

query: str

count: int | None

country: str | None

search_lang: str | None

ui_lang: str | None

safesearch: str | None

future: Future

user_api_key: str | None = None

user_id: str | None = None

redis_client: object | None = None

class tools.brave_search.BraveSearchRateLimiter(calls_per_interval=0.5, interval_seconds=1.0)[source]

Bases: object

Global rate limiter that serialises Brave API calls.

Parameters:

calls_per_interval (float)
interval_seconds (float)

__init__(calls_per_interval=0.5, interval_seconds=1.0)[source]

Initialize the instance.

Parameters:

calls_per_interval (float) – The calls per interval value.
interval_seconds (float) – The interval seconds value.

task_queue: Queue | None

last_call_time: float

async search(query, count=10, country=None, search_lang=None, ui_lang=None, safesearch='moderate', user_api_key=None, user_id=None, redis_client=None)[source]

Perform search.

Parameters:

query (str) – Search query or input string.
count (Optional[int]) – Number of results to return.
country (Optional[str]) – The country value.
search_lang (Optional[str]) – The search lang value.
ui_lang (Optional[str]) – The ui lang value.
safesearch (Optional[str]) – The safesearch value.
user_api_key (Optional[str]) – The user api key value.
user_id (Optional[str]) – Unique identifier for the user.
redis_client (Optional[object]) – Redis connection client.

Returns:

Result string.

Return type:

str

async tools.brave_search.search_with_key(query, count=3, api_key=None)[source]

Execute a Brave search through the shared rate limiter.

This is the entry point for internal callers (e.g. WebSearchContextManager) that already have a resolved API key and don’t need the tool-context ceremony.

Return type:

str

Parameters:

query (str)
count (int)
api_key (str | None)

async tools.brave_search.run(query, count=10, country=None, search_lang=None, ui_lang=None, safesearch='off', ctx=None)[source]

Execute this tool and return the result.

Parameters:

query (str) – Search query or input string.
count (int) – Number of results to return.
country (str) – The country value.
search_lang (str) – The search lang value.
ui_lang (str) – The ui lang value.
safesearch (str) – The safesearch value.
ctx – Tool execution context providing access to bot internals.

Returns:

Result string.

Return type:

str