Brave Search API

Relevant source files

The following files were used as context for generating this wiki page:

• core/integrations.py
• core/commands.py
• core/bot.py
• core/helpers.py
• tests/test_commands.py

The Brave Search API integration within the GentelmeN-CorE project provides a mechanism for the bot to access real-time web information. It serves two primary purposes: fulfilling explicit user search requests via dedicated commands and augmenting AI chat responses with "Net Info" when specific keywords (such as cryptocurrency prices or news) are detected in a conversation.

This integration allows the bot to move beyond its static training data by fetching the latest web results, which are then formatted for display or injected into the AI's system prompt to ensure up-to-date responses.

Sources: core/commands.py:145-151, core/commands.py:214-218

System Architecture and Integration

The Brave Search integration is encapsulated within the core/integrations.py module and utilized by the command handlers in core/commands.py. It relies on an external API key provided via environment variables to authenticate with Brave's search services.

Core Components

The integration consists of several key functional components:

• API Configuration: Retrieves the BRAVE_API_KEY from the environment.
• Search Function (search_brave): The primary interface for performing web queries. It handles HTTP requests, header management, and response parsing.
• Command Handler (explicit_search): Processes the /szukaj Telegram command.
• AI Context Augmentation: Automatically triggers searches during ai_chat based on keyword detection.

Sources: core/integrations.py:7, core/integrations.py:10-28, core/commands.py:145-159

Request Flow Diagram

The following diagram illustrates how a user request for a search is processed through the system, from the Telegram command to the Brave API and back.

The data flow ensures that raw API data is sanitized and formatted before being sent back to the user interface.
Sources: core/commands.py:145-159, core/integrations.py:10-28, core/helpers.py:1-15

Functional Implementation

search_brave Function

The search_brave function is the core logic for interacting with the Brave Search endpoint https://api.search.brave.com/res/v1/web/search.

Parameter	Type	Default	Description
query	String	Required	The search term or phrase.
count	Integer	3	The number of search results to return.

Logic Details:

1. Authentication: Uses the X-Subscription-Token header.
2. Request Parameters: Sets text_decorations to False to ensure clean text output.
3. Data Extraction: Iterates through data['web']['results'] to extract the title and description of each result.
4. Error Handling: Catches requests.RequestException and returns an empty string if the API is unreachable or fails.

Sources: core/integrations.py:10-28

Explicit Search Command

Users can trigger a search manually using the /szukaj command. The bot utilizes a helper to send a "typing" action to the chat while the API request is in progress to improve user experience.

def explicit_search(m):
    parts = m.text.split(maxsplit=1)
    query = parts[1].strip() if len(parts) > 1 else ''
    if not query:
        return inteligentna_odpowiedz(_bot, m.chat.id, "🌐 Użyj: `/szukaj ai news`", ...)
    _bot.send_chat_action(m.chat.id, 'typing')
    results = search_brave(query, count=5)
    # ... response handling

Sources: core/commands.py:145-155

AI Context Augmentation (RAG-lite)

The project implements a simplified Retrieval-Augmented Generation (RAG) pattern within the ai_chat function. When the bot identifies specific keywords, it performs a background search and injects the results into the AI's system message.

Sequence of AI Augmentation

The triggered keywords include: cena, news, bitcoin, kurs, and price.
Sources: core/commands.py:214-218

Testing and Validation

The Brave Search integration is covered by unit tests in tests/test_commands.py and tests/test_integrations.py (referenced via logic).

Test Scenarios:

• Missing API Key: Verified that the function returns an empty string if BRAVE_KEY is not set.
• Successful Retrieval: Mocking API responses to ensure the formatter correctly joins titles and descriptions.
• API Errors: Ensuring RequestException and HTTP errors (like 404) are handled gracefully without crashing the bot.

Sources: tests/test_commands.py:157-195

Configuration

The integration requires the following environment variable to be defined in the hosting environment (e.g., Railway):

Variable	Description	Source File
BRAVE_API_KEY	Subscription token for Brave Search API	core/integrations.py:7

If this key is absent, the bot will skip search functions and return empty results or usage instructions.
Sources: core/integrations.py:11-12, railway.json:1-12