Платформа для Telegram-ботов на Python: YAML-конфиги вместо кода

Многим знакомая боль: каждый новый Telegram-бот приходится писать с нуля или платить за разные сервисы, а кастомизация упирается в их ограничения. Хочется self-hosted решение, где можно гибко настраивать логику, не переписывая код каждый раз.

Coreness — платформа на Python для развёртывания AI-ботов через YAML-конфиги. Один сервер, сколько угодно изолированных тенантов, свои LLM-модели, RAG из коробки. И теперь проект выходит в open source.

Сайт: coreness.tech

Документация: docs.coreness.tech • GitHub

Coreness построен на event-driven архитектуре с четким разделением слоёв.

Telegram отправляет обновления, платформа находит подходящий YAML-сценарий, выполняет действия через сервисы и сохраняет данные в PostgreSQL с автоматической изоляцией по тенантам.

Всё асинхронно, боты могут параллельно обрабатывать входящие события.

Полная изоляция данных на уровне базы. Один экземпляр платформы — множество независимых ботов:

Свои настройки, базы знаний, промпты для каждого тенанта
Автоматическая фильтрация по tenant_id через Row-Level Security — не нужно добавлять условия в каждый запрос
GitHub-синхронизация конфигураций (Infrastructure as Code)
Master Bot — готовый бот для управления тенантами (аналог @BotFather)

Для добавления нового бота достаточно просто создать папку с конфигом, и платформа подхватывает его автоматически.

Декларативное описание сценариев — вся логика в конфигах:

start: trigger: - event_type: "message" event_text: "/start" step: - action: "send_message" params: text: | 👋 Привет, {first_name|fallback:друг}! Добро пожаловать в бота! inline: - [{"📋 Меню": "menu"}, {"ℹ️ Помощь": "help"}]

Что здесь происходит:

trigger — условие запуска (команда /start)
step — последовательность действий
{first_name|fallback:друг} — плейсхолдер с модификатором (если first_name пустой, подставится "друг")
inline — кнопки под сообщением

Сценарии описываются декларативно — не нужно разбираться в коде платформы, достаточно знать структуру конфига. Логику может менять не только программист: PM настроит флоу, маркетолог обновит тексты, дизайнер поправит кнопки. Всё в одном читаемом файле.

Встроенная интеграция с LLM-моделями и векторным поиском:

Semantic search через pgvector (PostgreSQL)
Поддержка OpenAI, Anthropic, Google, DeepSeek через агрегаторы (OpenRouter, Azure OpenAI и другие)
RAG-контекст в сценариях — боты отвечают на основе базы знаний
Function calling и AI-агенты с инструментами

Пример использования RAG:

ai_answer: trigger: - event_type: "message" step: # Поиск релевантного контекста - action: "search_embedding" params: query_text: "{event_text}" document_type: "knowledge" limit_chunks: 5 # AI ответ с контекстом - action: "completion" params: prompt: "{event_text}" system_prompt: "Ты — помощник. Используй контекст для точных ответов." rag_chunks: "{_cache.chunks}" model: "gpt-4o-mini" # Отправка ответа - action: "send_message" params: text: "{_cache.response}"

Система автоматически формирует правильную структуру messages для AI, группирует чанки по типам (история диалога, база знаний, дополнительный контекст).

Автоматизация по расписанию через cron-выражения:

daily_report: schedule: "0 9 * * *" # Каждый день в 9:00 step: - action: "send_message" params: text: "Доброе утро! Вот отчёт за вчера..."

Полезно для ежедневных отчётов, рассылок, периодических проверок.

Каждая фича — отдельный плагин в папке plugins/. Нужна интеграция с внешним API? Не проблема, достаточно написать новый плагин и добавить в папку.

Структура:

plugins/ ├── utilities/ # Вспомогательные утилиты │ ├── foundation/ # Базовые (logger, plugins_manager) │ ├── telegram/ # Telegram утилиты │ └── core/ # Инфраструктурные (event_processor, database) └── services/ # Бизнес-сервисы ├── bot_hub/ # Управление ботами ├── tenant_hub/ # Управление тенантами └── ai_service/ # AI и RAG

Плагины изолированы, общаются через события. Добавляется новый плагин — система подхватит и свяжет зависимости, сервис регистрирует свои действия через action_hub.

Каждый сервис самодостаточен, общается через события. Не запутанная сеть зависимостей, а чистые вертикальные срезы функциональности.

Как обрабатывается событие на практике:

Разберём на примере сообщения с RAG-ответом (как на диаграмме):

Telegram Bot API отправляет webhook с новым сообщением
Event Processor парсит Update асинхронно и создаёт Task
Scenario Engine ищет триггер в YAML-сценариях и находит подходящий
Step Executor последовательно выполняет actions из сценария:
Step 1: search_embedding → AI Service обращается к PostgreSQL pgvector, получает релевантные chunks
Step 2: completion → AI Service отправляет prompt + RAG chunks в OpenRouter/LLM, получает ответ
Step 3: send_message → Telegram Utility вызывает Bot API, отправляет ответ пользователю
Task завершается, пользователь получает ответ

Вся магия подключения плагинов через Dependency Injection. Добавил плагин в папку — система сама подхватила, связала зависимости, внедрила нужные сервисы. Регистрация действий плагинов происходит через action_hub — центральный хаб, который маршрутизирует действия к соответствующим сервисам.

Автоматическая фильтрация данных на уровне базы. Один SELECT-запрос — PostgreSQL сам ограничивает выборку по tenant_id.

Не нужно в каждом запросе добавлять WHERE tenant_id = ..., база сама фильтрует на уровне строк. Это критично для мультитенантности — невозможно случайно получить данные другого тенанта.

Дополнительно: система автоматически создаёт PostgreSQL view для контроля доступа на уровне БД. Можно настроить read-only пользователей с доступом к конкретным тенантам через таблицу view_access.

Альтернатива: для упрощённой настройки можно использовать SQLite вместо PostgreSQL. Не нужен отдельный контейнер, проще администрирование, меньше DevOps-проблем. Ограничение: в SQLite не работает RAG (нет поддержки pgvector), поэтому векторный поиск недоступен. Для production с RAG рекомендуется PostgreSQL.

Окей, теория понятна. Как это работает на практике?

Платформа включает утилиту Core Manager для развёртывания и обновлений. Она настраивает окружение, БД и контейнеры «под ключ», поддерживает русский и английский интерфейс.

# Клонируем репозиторий git clone https://github.com/Vensus137/Coreness.git cd Coreness # Запускаем Core Manager python tools/core_manager/core_manager.py

При первом запуске утилита запросит:

Окружение (test / prod) — тестовое или продакшн
Режим развёртывания (docker / native) — контейнеры или нативный запуск (на Windows удобнее native)
Язык интерфейса (English / Русский)

Настройки сохраняются в config/.version. Далее в меню: обновление системы из GitHub (с миграциями и бэкапом), работа с БД (миграции, бэкап, восстановление), самообновление утилиты, смена языка.

Подробнее — в документации по деплою.

Создаём папку config/tenant/tenant_101/ с файлом tg_bot.yaml:

bot_name: "Мой бот" bot_token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz" is_active: true

Создаём файл config/tenant/tenant_101/scenarios/start.yaml:

start: trigger: - event_type: "message" event_text: "/start" step: - action: "send_message" params: text: | 👋 Привет, {first_name}! Это бот на платформе Coreness. inline: - [{"📋 Меню": "menu"}, {"ℹ️ Помощь": "help"}] menu: trigger: - event_type: "callback" callback_data: "menu" step: - action: "send_message" params: text: "Выберите действие:" inline: - [{"🤖 О боте": "about"}] - [{"🔙 Назад": "start"}]

Добавим сценарий с RAG для ответов на вопросы. Создаём config/tenant/tenant_101/scenarios/ai.yaml:

save_knowledge: trigger: - event_type: "message" event_text: "/save_docs" step: - action: "save_embedding" params: text: | Coreness — это платформа для создания Telegram ботов. Основные возможности: - Сценарии на YAML - Хранилище данных (storage) - Работа с оплатами - RAG для контекстных ответов document_type: "knowledge" role: "user" ask_question: trigger: - event_type: "message" step: # Поиск релевантного контекста - action: "search_embedding" params: query_text: "{event_text}" document_type: "knowledge" limit_chunks: 3 min_similarity: 0.7 # AI ответ с контекстом - action: "completion" params: prompt: "{event_text}" system_prompt: "Ты — помощник. Отвечай на основе предоставленного контекста." rag_chunks: "{_cache.chunks}" model: "gpt-4o-mini" # Отправка ответа - action: "send_message" params: text: "{_cache.response_complition}"

Что здесь происходит:

save_knowledge — сохраняет текст в векторное хранилище
ask_question — ищет релевантные фрагменты и отправляет их в AI
Система автоматически формирует контекст для модели

Если используется GitHub-синхронизация:

# Push в репозиторий git add config/tenant/tenant_101/ git commit -m "Add tenant 101" git push # Webhook автоматически синхронизирует изменения

Или принудительно через Master Bot:

Открываем master_bot
Отправляем /tenant
Вводим ID тенанта (101)
Нажимаем "Синхронизация"

Готово. Бот отвечает на команды, обрабатывает кнопки, всё работает.

Важно: Это минимальный пример. В реальности можно добавить:

AI-ответы с RAG
Оплаты через Telegram Stars
Scheduled сценарии
Валидацию и переходы
Storage для хранения данных пользователей

Всё это настраивается через YAML, без единой строки кода.

Пример бота

Как добавить монетизацию? Собственно, через платежный модуль телеграмм. Разберем на примере Telegram Stars:

buy_premium: trigger: - event_type: "message" event_text: "/buy" step: - action: "create_invoice" params: title: "Премиум подписка" description: "Доступ к премиум функциям на 1 месяц" amount: 100 # 100 звезд currency: "XTR" handle_pre_checkout: trigger: - event_type: "pre_checkout_query" step: # Подтверждаем платеж (критично - таймаут ~10 сек) - action: "confirm_payment" params: pre_checkout_query_id: "{pre_checkout_query_id}" invoice_payload: "{invoice_payload}" handle_payment_successful: trigger: - event_type: "payment_successful" step: # Отмечаем инвойс как оплаченный - action: "mark_invoice_as_paid" params: invoice_payload: "{invoice_payload}" telegram_payment_charge_id: "{telegram_payment_charge_id}" # Активируем подписку - action: "set_user_storage" params: key: "premium_active" value: true # Отправляем подтверждение - action: "send_message" params: text: "✅ Платеж успешно обработан! Премиум активирован."

Что здесь происходит:

Пользователь отправляет /buy → создаётся инвойс
Пользователь нажимает "Оплатить" → Telegram отправляет pre_checkout_query
Бот подтверждает платеж через confirm_payment (в течение 10 секунд)
Telegram обрабатывает платеж → отправляет payment_successful
Бот отмечает инвойс как оплаченный и активирует подписку

Вся логика оплат в конфиге. Не нужно писать код обработки платежей вручную.

Для оплаты в валюте достаточно заменить атрибут currency и подключить соответствующего провайдера в настройках бота в телеграмм.

Python 3.11+ с прямой работой через Telegram Bot API (без aiogram — меньше зависимостей, выше производительность)
PostgreSQL 16+ с расширением pgvector для RAG (или SQLite для упрощённой версии)
Docker + docker-compose для развёртывания
Агрегаторы LLM для доступа к моделям (OpenAI, Anthropic, Google, DeepSeek через OpenRouter, Azure OpenAI и другие)

Почему без aiogram? Прямая работа с Telegram Bot API через aiohttp экономит ресурсы, работает быстрее, меньше зависимых библиотек. Всё что нужно — обработка JSON и HTTP-запросы.

Впрочем, это архитектурное решение. Можно добавить aiogram-адаптер через плагин, если нужна совместимость.

Асинхронная обработка событий через asyncio — все операции неблокирующие
Кэширование данных и настроек — снижает нагрузку на БД
Оптимизация векторного поиска через HNSW-индексы pgvector — быстрый поиск даже на больших объемах
Параллельная обработка — боты могут параллельно обрабатывать входящие события
Прямая работа с Telegram Bot API — без промежуточных библиотек, меньше overhead

При росте нагрузки можно масштабировать платформу несколькими способами:

Вертикальное масштабирование:

Увеличение ресурсов сервера (CPU, RAM) — самый простой путь
Настройка PostgreSQL (shared_buffers, work_mem) под нагрузку
Оптимизация пула соединений к БД

Горизонтальное масштабирование:

Несколько инстансов приложения — запуск нескольких экземпляров за load balancer
PostgreSQL read-replicas — для чтения (поиск по RAG, получение конфигов), запись в master
Redis для кэширования — опционально, снижает нагрузку на БД при частых запросах

Особенности архитектуры:

Event-driven упрощает распределение нагрузки — события обрабатываются независимо
Мультитенантность через RLS работает одинаково на любом количестве инстансов
Важно: при использовании webhooks нужна единая точка входа (load balancer), webhook привязан к одному URL

Для большинства случаев достаточно вертикального масштабирования. Горизонтальное имеет смысл при высокой нагрузке (сотни ботов, тысячи сообщений в секунду).

Изоляция данных на уровне БД — невозможно случайно получить данные другого тенанта
Валидация через Pydantic — все входные параметры проверяются по схемам
Secrets вынесены в переменные окружения — токены и ключи не хранятся в коде
Автоматические бэкапы БД с настраиваемым интервалом — защита от потери данных
Гибкая настройка доступов — можно сконфигурировать read-only пользователей с доступом к конкретным тенантам, полезно для аналитики и аудита

Утилита Core Manager управляет развёртыванием и обновлениями:

Обновление системы из GitHub — выбор версии, бэкап, обновление файлов, миграции БД, перезапуск контейнеров (docker) или установка зависимостей (native)
Работа с БД — миграции, создание бэкапа, восстановление из бэкапа
Самообновление утилиты — загрузка новой версии Core Manager с GitHub
Файлы настроек и версии не перезаписываются при обновлении

# Запуск Core Manager python tools/core_manager/core_manager.py # Меню: # 1. Обновление системы # 2. Работа с БД # 3. Обновить утилиту # 4. Сменить язык

Проект выходит в open source, чтобы развивать его вместе с сообществом.

Расширение возможностей RAG — поддержка файлов (PDF, DOCX), улучшенная обработка документов
Больше готовых плагинов — интеграции с популярными API и сервисами, новые функции и возможности
Упрощение Master Bot — улучшенное управление тенантами через интерфейс
Выход в мини-апп Telegram — дополнительные возможности управления тенантами и новые функции через Telegram Mini App

Если тема зашла — ставьте звезду на GitHub, пробуйте в своих проектах и пишите в Issue или напрямую автору. Любой фидбек помогает развивать проект.

Репозиторий: github.com/Vensus137/Coreness
Сайт: coreness.tech
Документация: docs.coreness.tech
Telegram-канал: t.me/coreness
Связь с автором: @vensus137

Coreness — Create. Automate. Scale.

Платформа для Telegram-ботов на Python: YAML-конфиги вместо кода

Возможности платформы

Архитектура платформы

Multi-tenancy из коробки

YAML-конфигурации вместо кода

RAG и AI-агенты

Scheduled сценарии

Плагинная система

Как это работает

Event-Driven + Vertical Slices

Автоматическое управление зависимостями

Изоляция данных через PostgreSQL

Запускаем бота за 5 минут

Шаг 1. Разворачиваем через Core Manager

Шаг 2. Создаём тенант

Шаг 3. Настраиваем сценарий

Шаг 4. Загружаем базу знаний (опционально)

Шаг 5. Синхронизируем

Результат

Бонус: Добавляем оплаты

Технологии и реализация

Стек

Производительность

Масштабирование

Безопасность

Система деплоя

Что дальше

Ближайшие направления

Ссылки