Multi-LLM Telegram Bot (ChatGPT, Gemini, Mistral, Cerebras)

Русский | English

A powerful and flexible Telegram bot that combines the capabilities of advanced language models: OpenAI (GPT-4o), Google (Gemini 2.5, Thinking), Mistral AI, and Cerebras.

The project is built on a modern stack (Python 3.10+, Aiogram-style architecture, MongoDB) and lets you deploy your own AI assistant without strict limitations, with support for vision, document analysis, and long-term memory.

✨ Key features

• Multi-model: The model is selected automatically based on the chosen chat mode. Configuration is fully customizable via YAML.
• Ultra-fast responses: Support for the Cerebras provider and Grok for instant answer generation (400+ tokens per second).
• Vision support: Send the bot photos and it will recognize their content (via GPT-4o, Gemini, or Llama 3.2 Vision).
• File handling: Upload documents in PDF, DOCX, TXT, PY, MD, CSV, XLSX, XLS formats (up to 5 MB). The bot reads their content and uses it in the conversation context.
• Thinking Models: Full support for models with a "chain of thought" (Reasoning) — the bot can show its reasoning before the final answer.
• Streaming: Answers are printed in real time, creating a live-conversation effect.
• Long-term memory: The /remember command lets you save facts about yourself (name, tech stack, preferences) that are automatically injected into the context of every request.
• Chat modes (Personas): Over 18 built-in roles with unique prompts: 👩🏼‍💻 IT expert, 🧠 Psychologist, 🇬🇧 Tutor, 🚀 Elon Musk, and more.
• Roleplay: A roleplay mode with customizable scenarios and stories.
• Educational mode: Interactive learning with question generation and answer checking.
• Data analysis: A mode for analyzing data from CSV and Excel files, generating reports and insights.
• Group support: The bot can be added to a group chat — it responds when mentioned or replied to.
• Admin panel: A "whitelist" system (approve/ban) for new users, token statistics, and message broadcasting (/broadcast).
• Improved UX: Visual loading indicators, emojis, and formatting for a better user experience.

🤖 Commands

Main

• /new — Start a new conversation (reset context).
• /mode — Choose a chat mode (switch persona).
• /retry — Regenerate the bot's last answer.
• /profile — User profile and personal token usage statistics.
• /remember [text] — Remember a fact. Example: /remember I code in Python, use Python code examples.
• /help — Help.

Roleplay

• /start_role [scenario] — Start a roleplay session with a given scenario.
• /end_role — End the current roleplay session.
• /role_history — Show the roleplay history.

Educational mode

• /learn [topic] — Start learning a new topic.
• /question — Get a learning question on the current topic.
• /answer [answer] — Submit an answer to the current question.
• /progress — Show learning progress.
• /topics — Show the list of topics to learn.

For admins

• /users — Show the list of users (pending approval and active).
• /approve [id|username] — Grant access to a user.
• /ban [id|username] — Block access.
• /broadcast [message] — Send a message to all active users.
• /stats — Overall token usage statistics across all models.

🧠 Supported providers

The bot uses a flexible "backends" system configurable in config/models.yml. Supported:

1. Unified / Proxy (Main): A universal client for any OpenAI-compatible API. Ideal for connecting via:
   • Local proxies (Copilot Proxy, DeepSeek).
   • Local LLMs (LM Studio, Ollama, vLLM).
   • Third-party aggregators.
2. Google Native: Direct support for Gemini 1.5 / 2.5 via the new google-genai SDK. Supports Search and native vision.
3. OpenAI Native: Official API (GPT-3.5, GPT-4o).
4. Mistral AI: Native support for Mistral Large and Codestral.
5. Cerebras: Inference support on Wafer-Scale Engine chips (Llama 3.3, Qwen).

🛠 Installation and running

Prerequisites

• Python 3.10+ (or Docker)
• MongoDB (required, for storing history and users)

1. Configuration

1. Copy the example files:

   cp config/config.example.yml config/config.yml
   cp config/config.example.env config/config.env

2. Edit config/config.yml. Fill in only the keys you plan to use:

   telegram_token: "123456:ABC-..."
   
   # API Keys (leave null if unused)
   openai_api_key: "sk-..."
   google_api_key: "AIza..." # For Gemini
   unified_api_key: "sk-..." # For OpenAI-compatible proxies
   
   # List of IDs or usernames of admins (for access to admin commands)
   allowed_telegram_usernames: [123456789, "my_username"]

3. Configure the models in config/models.yml. You can add your own models by simply specifying api_base and model_name.

2. Running via Docker (Recommended)

The project includes a docker-compose.yml that brings up the bot and a MongoDB database.

1. Specify the DB parameters in config/config.env.

2. Start the containers:

   docker-compose up --build -d

3. Manual launch

1. Make sure MongoDB is running and accessible.

2. Install dependencies:

   pip install -r requirements.txt

3. Start the bot:

   python bot/main.py

4. Quick start with a local model (for testing)

If you want to quickly test the bot without external APIs:

1. Install Ollama: https://ollama.ai/
2. Pull a model: ollama pull llama3
3. Start the server: ollama serve
4. Make sure config/chat_modes.yml uses the ollama-llama3 model (set by default)
5. Provide the Telegram bot token in config/config.yml or config/config.env
6. Start the bot as described above

📂 Project structure

• bot/
  • handlers/ — Command logic (admin, message, user, menu, role_playing, learning).
  • llm/ — API clients (openai, gemini, unified).
  • database.py — A wrapper over MongoDB.
• config/
  • chat_modes.yml — Prompts for role modes.
  • models.yml — Registry of models and their settings.
• locales/ — Translation files (RU/EN).
• docs/guides/EXAMPLES.md — Usage examples and scenarios

🎮 New features

Roleplay

The bot now supports a roleplay mode where you can create a scenario and interact with characters in a virtual world. Use the /start_role, /end_role, and /role_history commands to manage sessions.

Educational mode

In learning mode, the bot can generate questions on the topics you study, check your answers, and track progress. Use the /learn, /question, /answer, /progress, and /topics commands.

Data analysis

The bot can analyze data from CSV and Excel files, providing statistics, insights, and recommendations. Just upload a file in "📊 Data Analyst" mode.

Improved UX

• Visual loading indicators with updating text
• Emojis and formatting for better readability
• Improved messages and hints

License

MIT