Creating Custom Bot Commands

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/helpers.py
• core/integrations.py
• tests/test_commands.py

Custom bot commands in the GentelmeN-CorE system are built using the pyTelegramBotAPI library. The architecture separates command logic, database persistence, and external integrations to allow for modular expansion. Commands are typically defined as Python functions that receive a message object and use a centralized handler registration system to link Telegram commands to their respective logic.

The system supports various types of commands, including AI-driven chat interactions, cryptocurrency price checks, alert management, and image generation. Each command follows a pattern of input validation, optional database interaction, and response dispatch through a helper utility named inteligentna_odpowiedz.

Sources: core/commands.py, core/bot.py, requirements.txt:1

Command Architecture and Registration

The command system relies on a registration pattern where the Telegram bot instance is passed to a dedicated function that binds commands to functions.

Handler Registration

The register_handlers function in core/commands.py serves as the entry point for connecting the bot instance to command functions. It uses the bot.message_handler decorator syntax to map specific command strings (e.g., /start, /cena) to their implementation functions.

Command Structure

A standard command function accepts a single parameter m (the Telegram message object). It typically performs the following steps:

1. Validation: Checks user permissions (e.g., ADMIN_ID) or input format.
2. Action: Performs logic such as calling the KuCoin API or querying the database.
3. Response: Uses inteligentna_odpowiedz to send formatted text or media back to the user.

Sources: core/commands.py:28-44, core/helpers.py:1-16

Security and Authorization

The system implements basic authorization checks for sensitive commands. Admin-only commands check against an ADMIN_ID environment variable, while financial commands like /balance use a specific authorized username or an OWNER_USER_ID.

Command	Restriction Level	Logic Source
/alert	Admin Only	m.from_user.id != ADMIN_ID
/alerty	Admin Only	m.from_user.id != ADMIN_ID
/balance	Owner Only	str(m.from_user.id) == owner_user_id or username check

Sources: core/commands.py:47-48, core/commands.py:85-98

Integration with External APIs

Commands often bridge Telegram interactions with external services. The core/integrations.py module handles the specific API calls, while the command functions manage the user interface.

Example: Image Generation Flow

The /rysuj command demonstrates the flow from a user prompt to an external API (HuggingFace) and back to the user as a photo.

Data Persistence and User Context

Commands can modify user state or preferences stored in a PostgreSQL database. The core/database.py module provides functions to update and retrieve user settings like preferred language or AI model.

User Preferences

When a user runs /start, the welcome command initializes their record in the database. Subsequent commands like /en or /llama update these preferences via update_user_db.

Field	Type	Description
user_id	BIGINT	Unique Telegram User ID (Primary Key)
language	TEXT	Preferred AI response language (EN/PL)
model_name	TEXT	AI model identifier (e.g., llama-3.3-70b-versatile)

Sources: core/database.py:15-28, core/commands.py:127-130

Implementation Example: Cryptocurrency Alert

The alert system combines user input, database storage, and a background monitoring thread.

def set_alert(m):
    # 1. Permission check
    if m.from_user.id != ADMIN_ID:
        return inteligentna_odpowiedz(...)
    
    # 2. Input parsing
    parts = m.text.upper().split()
    symbol, target = parts[1], float(parts[2])
    
    # 3. Database entry
    with psycopg2.connect(DB_URL) as conn:
        cur.execute("INSERT INTO alerts ...")

Sources: core/commands.py:47-75, core/bot.py:41-80

Price Monitoring Sequence

A separate thread in core/bot.py continuously monitors the prices for all saved alerts and notifies users when thresholds are met.

Summary

Creating custom bot commands in GentelmeN-CorE involves defining a logic function, ensuring proper parameter extraction from the message object, and registering the function within register_handlers. The use of modular integrations and a central database allows commands to perform complex tasks while maintaining a clean separation of concerns.