Telegram Command Handlers

Relevant source files

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

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

The Telegram Command Handlers represent the core interaction layer of the GentelmeN-CorE bot. This system manages user requests, processes specialized commands for cryptocurrency data, image generation, and web searches, and facilitates an AI-driven chat experience. The handlers are built on the pyTelegramBotAPI (telebot) framework and interface with external services including Groq (LLM), KuCoin (Crypto exchange), Brave Search, and Hugging Face (AI Image generation).

Sources: core/commands.py:214-230, core/bot.py:21-25

Architecture and Registration

The command handler logic is centralized in core/commands.py, where various functions are defined to handle specific Telegram /commands. These handlers are registered to the bot instance via the register_handlers function, which maps commands to their respective Python functions.

Command Registration Flow

The initialization sequence ensures that global clients for Groq and KuCoin are available to all handler functions before the bot starts polling.

The registration process utilizes the bot.message_handler decorator pattern to bind specific strings to logic.

Sources: core/commands.py:214-230, core/bot.py:65-72

Command Categories

1. Cryptocurrency & Financial Tools

These handlers interact with the KuCoin API through the ccxt library to fetch market data and manage user alerts.

Command	Function	Description
/cena [sym]	check_price	Fetches the latest ticker price for a symbol (e.g., BTC/USDT).
/alert [sym] [val]	set_alert	Sets a price threshold (Admin only) to trigger a notification.
/alerty	list_alerts	Displays active price alerts stored in the database.
/balance	check_balance	Shows account balances (Authorized users only).

Sources: core/commands.py:27-109, core/bot.py:30-36

2. AI & Media Generation

The system leverages external AI providers to generate content based on user prompts.

• Image Generation (/rysuj): Extracts a prompt from the user's message and sends it to the Hugging Face Inference API, specifically using the FLUX.1-schnell model.
• Voice Processing: Handles voice content types by downloading the .ogg file, transcribing it via Groq's Whisper model, and either routing it to image generation (if the transcription starts with "rysuj") or standard AI chat.

3. Information Retrieval

Handlers for web-based data retrieval utilize the Brave Search API and the GitHub Search API.

• Brave Search (/szukaj): Performs a web search and returns formatted snippets including titles and descriptions.
• GitHub Search (/github): Searches for repositories, returning links and star counts for the top 3 results.

Sources: core/commands.py:143-166, core/integrations.py:9-25

AI Chat Logic

The ai_chat function serves as the fallback handler for all text messages that do not match a specific command.

• Context Management: Maintains a per-user history in user_history up to a MAX_HISTORY of 40 messages to provide conversational context.
• Dynamic System Prompt: Injects localized instructions based on the user's preferred language (stored in PostgreSQL).
• Web Augmentation: If keywords like "cena" or "news" are detected in the user's input, the system automatically performs a Brave search and appends the results to the AI's system message for grounded responses.

Sources: core/commands.py:204-230, core/database.py:46-64

Data Persistence & Preferences

User preferences regarding AI models (e.g., llama-3.3-70b-versatile, qwen-2.5-32b) and interface language (EN/PL) are persisted in a PostgreSQL database.

Field	Type	Description
user_id	BIGINT	Primary key (Telegram User ID).
language	TEXT	'EN' or 'PL' preference.
model_name	TEXT	Selected Groq model for chat.
joined_at	TIMESTAMP	Record creation time.

Sources: core/database.py:15-25, core/commands.py:126-141

Conclusion

The Telegram Command Handlers in GentelmeN-CorE provide a versatile interface for various tools, ranging from financial monitoring to AI content generation. By utilizing a modular architecture where handlers are registered centrally but logic is delegated to integration and database modules, the system remains extensible and capable of maintaining stateful user interactions.