Web & GitHub Search Integration

Relevant source files

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

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

The Web & GitHub Search Integration module provides the GentelmeN-CorE bot with real-time information retrieval capabilities. It bridges the gap between static LLM training data and current events or technical resources by leveraging external APIs. The system supports explicit user-triggered searches and implicit context enrichment during AI conversations.

This integration primarily utilizes the Brave Search API for general web queries and the GitHub REST API for repository discovery. These tools allow the bot to provide formatted search results, including titles, descriptions, and repository statistics like star counts.

Sources: core/commands.py, core/integrations.py

Architecture and Data Flow

The search system is divided into low-level integration functions that handle HTTP requests and high-level command handlers that manage Telegram interactions.

Core Components

• Integration Layer: Contains the search_brave function which interfaces with the Brave Search API.
• Command Layer: Contains explicit_search and github_search functions that process user input and format the final output.
• AI Context Layer: The ai_chat function can trigger an implicit web search to provide the LLM with "Net Info" when specific keywords (e.g., "news", "bitcoin") are detected.

The following diagram illustrates the flow of a search request from the user to the external APIs and back.

Web Search Integration (Brave Search)

General web searching is powered by the Brave Search API. This is implemented in core/integrations.py and accessed via the /szukaj command or automatically during AI chat sessions.

Implementation Details

The search_brave function sends a GET request to https://api.search.brave.com/res/v1/web/search. It requires a BRAVE_API_KEY environment variable. If the key is missing, the function fails silently by returning an empty string.

Parameter	Type	Description	Default
query	String	The search term provided by the user.	N/A
count	Integer	Number of results to retrieve.	3

Sources: core/integrations.py:9-12, core/integrations.py:15-17

Implicit AI Search

When a user interacts with the bot via standard chat (without a specific command), the ai_chat function scans the text for keywords such as "cena", "news", "bitcoin", "kurs", or "price". If found, it invokes search_brave and prepends the results to the AI's system message as Net Info, allowing the model to answer based on current data.

    if any(w in m.text.lower() for w in ["cena", "news", "bitcoin", "kurs", "price"]):
        web_info = search_brave(m.text, count=2)
        if web_info:
            sys_msg += f"\nNet Info:\n{web_info}"

Sources: core/commands.py:252-256

GitHub Repository Search

The GitHub integration allows users to find repositories directly within Telegram using the /github command. Unlike the web search, this implementation resides directly within core/commands.py.

Search Logic

The system uses the GitHub Search API (https://api.github.com/search/repositories). It searches for repositories based on a query, sorting results by the number of stars in descending order.

• Authentication: Uses GITHUB_TOKEN from environment variables if available to increase rate limits.
• Result Limit: It retrieves the top 3 most relevant repositories.
• Formatting: Each result includes the full name (linked to the URL), star count, and the repository description.

Configuration and Environment Variables

The integration module relies on several environment variables for authentication and API access.

Variable	Source File	Purpose
BRAVE_API_KEY	core/integrations.py	Token for Brave Search API access.
GITHUB_TOKEN	core/commands.py	Personal Access Token for GitHub API (optional).
GROQ_KEY	core/bot.py	Required for AI context processing of search results.

Sources: core/integrations.py:6, core/commands.py:15, core/bot.py:15

Response Handling

All search results are dispatched through inteligentna_odpowiedz (intelligent response) defined in core/helpers.py. This utility ensures that:

1. Markdown formatting is respected.
2. Web page previews are disabled for search results to keep the chat clean.
3. Messages are correctly routed to specific Telegram threads if the bot is used in a group.

Sources: core/helpers.py:1-16, core/commands.py:175-179

Conclusion

The Web & GitHub Search Integration provides GentelmeN-CorE with a powerful mechanism for fetching external data. By combining explicit search commands with implicit AI context enrichment, the system ensures that users have access to both general web information and specific technical resources like GitHub repositories. The modular design allows for easy expansion or swapping of search providers by modifying the integration functions.