Relevant source files

The following files were used as context for generating this wiki page: - [core/bot.py](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/main/core/bot.py) - [core/commands.py](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/main/core/commands.py) - [core/database.py](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/main/core/database.py) - [core/integrations.py](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/main/core/integrations.py) - [core/helpers.py](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/main/core/helpers.py) - [bot.py](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/main/bot.py) - [railway.json](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/main/railway.json)

# GeNCorE Home GeNCorE (GentelmeN-CorE) is a multi-functional Telegram bot platform designed to integrate Large Language Models (LLMs), cryptocurrency market data, and external web services. The system operates as a centralized hub providing AI-driven chat capabilities, image generation, web searching, and real-time financial monitoring. The architecture follows a modular pattern where the core logic is separated into specialized modules for command handling, database persistence, and third-party integrations (e.g., Groq, KuCoin, Brave Search, and Hugging Face). It is designed for deployment on the Railway platform using a PostgreSQL backend for persistent storage of user preferences and crypto alerts. Sources: [core/bot.py](), [core/commands.py](), [railway.json]() ## System Architecture The GeNCorE system is built upon a Python-based core that utilizes `pyTelegramBotAPI` for interface management and `threading` for background tasks like price monitoring. The application entry point is `bot.py` at the root, which executes the primary logic located in `core/bot.py`. ### Core Components * **Bot Engine**: Managed in `core/bot.py`, it initializes the Telegram bot, Groq AI client, and KuCoin exchange interface. * **Command Dispatcher**: Located in `core/commands.py`, it registers all user-facing functions and routes Telegram messages to the appropriate logic. * **Persistence Layer**: Handled by `core/database.py`, using PostgreSQL to store user settings (language, model choice) and active price alerts. * **Integrations**: `core/integrations.py` provides abstracted access to the Brave Search API and Hugging Face Inference API. The following diagram illustrates the high-level data flow between the user, the bot core, and external services: ```mermaid flowchart TD User([Telegram User]) <--> TB[Telegram Bot API] TB <--> Core[GeNCorE Core] Core <--> DB[(PostgreSQL)] Core <--> Groq[Groq AI] Core <--> KuCoin[KuCoin API] Core <--> HF[Hugging Face] Core <--> Brave[Brave Search] ``` The diagram shows how the GeNCorE Core acts as a central orchestrator for user requests and external API responses. Sources: [core/bot.py:15-40](), [core/commands.py:236-258](), [bot.py:1-7]() ## AI and Language Processing GeNCorE leverages the Groq SDK to provide high-speed inference. It supports multiple LLM models and maintains a conversational history for each user to provide context-aware responses. ### Supported AI Models Users can switch between models using specific commands. The system defaults to `llama-3.3-70b-versatile` if no preference is found. | Command | Model Name | Description | | :--- | :--- | :--- | | `/llama` | `llama-3.3-70b-versatile` | High-capability versatile model | | `/fast` | `llama-3.1-8b-instant` | Optimized for speed/latency | | `/qwen` | `qwen-2.5-32b` | Alternative reasoning model | Sources: [core/commands.py:145-155](), [core/database.py:65-70]() ### Processing Flow 1. **Input Handling**: The bot accepts text and voice messages. Voice messages are transcribed using the `whisper-large-v3` model via Groq. 2. **Context Enrichment**: Before sending a prompt to the LLM, the system checks for keywords (e.g., "price", "news"). If found, it performs a real-time web search via Brave to provide up-to-date information. 3. **History Management**: A history of up to 40 messages is maintained per user in `user_history`. ```mermaid sequenceDiagram participant U as User participant C as Commands participant G as Groq (Whisper) participant B as Brave Search participant LLM as Groq (LLM) U->>C: Sends Voice Message C->>G: Transcribe Audio G-->>C: Transcription Text C->>B: search_brave(query) B-->>C: Search Results C->>LLM: Prompt (System + Search + History) LLM-->>C: AI Response C->>U: Final Answer ``` This sequence shows the transcription and search augmentation flow for a voice request. Sources: [core/commands.py:186-210](), [core/commands.py:213-233](), [core/integrations.py:10-25]() ## Cryptocurrency Integration The bot integrates with the KuCoin exchange via the `ccxt` library to provide real-time market data and private account balance tracking (for authorized administrators). ### Price Alerts A dedicated background thread, `price_monitor`, runs every 60 seconds. It fetches active alerts from the database, retrieves current prices for all required symbols in a single batch, and notifies users if thresholds are met. ### Authorization Sensitive operations like checking account balances or setting specific administrative alerts are restricted. The system validates the `from_user.id` against an `OWNER_USER_ID` or `ADMIN_ID` environment variable. Sources: [core/bot.py:44-84](), [core/commands.py:12-16](), [core/commands.py:70-85]() ## Database Schema The system initializes two primary tables in PostgreSQL to manage state. ### Table: `users` Stores metadata and preferences for individual users. | Field | Type | Description | | :--- | :--- | :--- | | `user_id` | BIGINT | Primary Key (Telegram ID) | | `username` | TEXT | Telegram Username | | `language` | TEXT | 'EN' or 'PL' (Default: 'EN') | | `model_name`| TEXT | Active LLM model | | `joined_at` | TIMESTAMP | Creation timestamp | ### Table: `alerts` Stores active price notifications. | Field | Type | Description | | :--- | :--- | :--- | | `id` | SERIAL | Primary Key | | `user_id` | BIGINT | Target user for notification | | `symbol` | TEXT | Trading pair (e.g., BTC/USDT) | | `target_price`| NUMERIC | Price threshold | | `direction` | TEXT | 'UP' or 'DOWN' | Sources: [core/database.py:15-35]() ## Deployment Configuration GeNCorE is configured for the Railway platform using the `RAILPACK` builder. The deployment environment requires several environment variables for full functionality. | Variable | Description | Required | | :--- | :--- | :--- | | `TELEGRAM_TOKEN` | API Token from BotFather | Yes | | `GROQ_KEY` | API Key for Groq AI | Yes | | `DATABASE_URL` | PostgreSQL connection string | Yes | | `KUCOIN_API_KEY` | KuCoin API Key | No (Crypto disable) | | `BRAVE_API_KEY` | Brave Search API Key | No (Web search disable) | | `HF_TOKEN` | Hugging Face Token | No (Image gen disable) | Sources: [railway.json:1-15](), [core/bot.py:15-20]() GeNCorE provides a robust framework for AI interaction by combining persistent user settings, real-time web data, and financial market monitoring into a single Telegram-based interface.