Telegram Interface & UX
Relevant source files
The following files were used as context for generating this wiki page:
The Telegram Interface & UX module serves as the primary interaction layer for the GentelmeN-CorE (GeNCorE) system. It leverages the pyTelegramBotAPI library to facilitate real-time communication between users and the bot's integrated AI and financial tools. The interface is designed to support multi-modal interactions, including text commands, natural language processing (NLP), and voice message transcription.
The system emphasizes a responsive user experience by utilizing Telegram's "chat actions" (e.g., typing, uploading photo) to provide visual feedback while backend processes, such as AI inference or image generation, are active. It also supports localization in English and Polish, as well as personalized AI model selection.
Sources: core/bot.py:12-25, core/commands.py:124-150, core/helpers.py:1-14
Command Architecture and Interaction Logic
The bot employs a structured command registration system to map specific Telegram commands to specialized handler functions. These handlers manage various aspects of the system, including cryptocurrency price checks, alert management, AI configuration, and external tool integration.
Handler Registration
Handlers are registered through the register_handlers function, which binds the Telegram TeleBot instance to various logic modules.
The diagram shows how incoming user messages are routed based on command prefixes or content types.
Sources: core/commands.py:255-273, core/bot.py:31
User Personalization
The UX is customized based on user data stored in a PostgreSQL database. Preferences include the preferred language (EN/PL) and the specific AI model to be used for responses (e.g., Llama 3.3, Qwen).
| Command | Action | Implementation Detail |
|---|---|---|
/en / /pl | Change Language | Updates language field in users table. |
/llama | Switch to Llama 3.3 | Sets model_name to llama-3.3-70b-versatile. |
/fast | Switch to Llama 3.1 | Sets model_name to llama-3.1-8b-instant. |
/qwen | Switch to Qwen 2.5 | Sets model_name to qwen-2.5-32b. |
/reset | Clear History | Purges the user_history dictionary for the session. |
Sources: core/commands.py:153-195, core/database.py:16-25
Response Handling and Visual Feedback
To maintain a high-quality UX, the bot uses a helper function inteligentna_odpowiedz (intelligent response). This utility ensures that messages are sent correctly within specific chat threads (supporting Telegram Topics) and allows for flexible Markdown parsing.
Visual Cues
The bot explicitly signals background activity to the user using the send_chat_action method:
typing: Used during AI text generation and web searches.upload_photo: Used during image generation with Hugging Face models.
Sources: core/commands.py:75, core/commands.py:202, core/commands.py:228, core/helpers.py:1-14
Sequence of an AI Interaction
This sequence illustrates the flow of a standard text-based interaction, highlighting the retrieval of user preferences and the use of visual feedback.
Sources: core/commands.py:238-251, tests/test_commands.py:19-35
Multi-Modal Interactions
Voice Messaging
The interface supports voice messages by downloading .ogg files and transcribing them via the Groq Whisper-3 model. If the transcribed text begins with "rysuj" (draw), the system automatically routes the request to the image generation module.
- Download: The bot retrieves the file from Telegram servers.
- Transcription: Sent to
whisper-large-v3. - Routing: If "rysuj" is detected, it calls
generate_image; otherwise, it proceeds toai_chat.
Sources: core/commands.py:208-234, tests/test_commands.py:257-295
Image Generation
The /rysuj command utilizes the Hugging Face Inference API (specifically the FLUX.1-schnell model) to generate images from text prompts. The generated content is returned as a BytesIO object and sent back to the user as a photo.
Sources: core/integrations.py:27-44, core/commands.py:220-226
Financial and Administrative Interfaces
The UX includes specialized components for interacting with the KuCoin exchange and managing persistent price alerts.
Price Alerts & Monitoring
Users (restricted to the Admin) can set price alerts that are monitored by a background thread.
- Command:
/alert [SYMBOL] [TARGET] - Logic: The bot determines the direction (UP/DOWN) based on the current price and saves it to the
alertstable. - Notification: A background thread in
core/bot.pypolls prices every 60 seconds and pushes a notification to the user when the target is hit.
| Table Field | Description |
|---|---|
symbol | The trading pair (e.g., BTC/USDT). |
target_price | The price threshold for triggering the alert. |
direction | Whether to alert on price crossing 'UP' or 'DOWN'. |
Sources: core/commands.py:46-65, core/bot.py:44-77, core/database.py:26-34
Balance Checks
Access to the /balance command is strictly controlled via the ADMIN_ID or OWNER_USER_ID environment variables. If an unauthorized user attempts to check the balance, the bot provides a refusal message containing the user's ID for identification.
Sources: core/commands.py:75-92, tests/test_commands.py:205-245
Summary
The Telegram Interface & UX of GeNCorE is a robust, thread-safe layer that bridges complex backend integrations (Crypto, AI, Web Search) with a user-friendly chat interface. By utilizing state management through PostgreSQL and session history through in-memory dictionaries, it provides a personalized and context-aware experience. The implementation of specific handlers for voice, images, and text ensures a versatile platform capable of handling diverse user needs.
Sources: core/bot.py:84-95, core/commands.py:117-124