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

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

Сайт проекта: coreness.tech

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

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

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

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

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

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

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

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

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

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

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

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

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 настроит флоу, маркетолог обновит тексты, дизайнер поправит кнопки.
Всё в одном читаемом файле.

RAG и AI-агенты

Встроенная интеграция с 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, группирует чанки по типам (история диалога, база знаний, дополнительный контекст).

Scheduled сценарии

Автоматизация по расписанию через 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

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

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

Event-Driven + Vertical Slices

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

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

Разберём на примере сообщения с 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 завершается, пользователь получает ответ

DI-контейнер координирует всё

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

Иерархия зависимостей:

Foundation (logger, plugins_manager, settings_manager)
    ↑
Custom Layers (telegram, ai, database)
    ↑
Core (event_processor, database_service)
    ↑
Services (bot_hub, tenant_hub, ai_service)

"Четкая иерархия предотвращает циклические зависимости и делает систему предсказуемой. Нижние слои не знают о верхних — классическая layered architecture."

PostgreSQL + RLS для изоляции

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

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

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

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

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

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

Шаг 1. Разворачиваем через deployment manager

Платформа включает утилиту для автоматизированного развёртывания. Она настраивает всё "под ключ": поднимает контейнеры, накатывает миграции, настраивает окружение.

# Клонируем репозиторий
git clone https://github.com/Vensus137/Coreness.git
cd Coreness

# Запускаем deployment manager
python tools/deployment/deployment_manager.py

Что происходит:

Утилита определяет окружение (test/prod)
Настраивает переменные окружения
Поднимает PostgreSQL 16 с pgvector (или SQLite для упрощённой версии)
Накатывает миграции базы
Собирает Docker-образ и запускает контейнеры
Устанавливает команду dc для управления

Важно: Для первого запуска нужно настроить config/settings.yaml и переменные окружения (токены ботов, ключи API). Deployment manager упрощает процесс установки и обновлений. Подробнее в документации по деплою.

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

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

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

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

Создаём файл 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"}]

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

Добавим сценарий с 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}"

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

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

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

Если используется 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-адаптер через плагин, если нужна совместимость.

Плагинная архитектура

Каждая фича — отдельный плагин в папке plugins/.

Пример структуры плагина:

plugins/services/ai_service/
├── ai_service.py           # Основной класс сервиса
├── config.yaml             # Конфигурация плагина
└── extension/              # Расширения
    ├── text_processor.py   # Обработка текста
    └── vector_storage_manager.py  # Работа с векторами

Пример регистрации сервиса:

class AIService:
    def __init__(self, action_hub, **kwargs):
        self.action_hub = action_hub
        
        # Регистрируем сервис в action_hub
        # action_hub автоматически построит маппинг действий
        # из конфигурации плагина (config.yaml)
        self.action_hub.register('ai_service', self)
    
    async def completion(self, data):
        # Логика AI-ответа
        # Метод должен совпадать с именем действия из config.yaml
        response = await self.ai_client.completion(
            prompt=data["prompt"],
            model=data.get("model", "gpt-4o-mini")
        )
        return {"result": "success", "response": response}

Как это работает: Действия описываются в config.yaml плагина в блоке actions. При регистрации сервиса action_hub автоматически строит маппинг действий из конфигурации. Методы в сервисе должны совпадать с именами действий из конфига. При вызове completion в YAML, action_hub маршрутизирует запрос к методу completion сервиса ai_service.

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

Асинхронная обработка событий через 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

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

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

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

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

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

Обновление сервера из GitHub с миграциями БД
Версионирование через git tags
Graceful shutdown при обновлении (корректное завершение работы)
Откат на предыдущую версию Docker-образа
Бэкапы файлов и БД перед обновлением

# Запуск системы деплоя
python tools/deployment/deployment_manager.py

# Меню:
# 1. Деплой в репозитории
# 2. Обновление сервера
# 3. Работа с БД
# 4. Откат Docker образа
# 5. Очистка старых образов

Планируемые фичи и улучшения

Проект выходит в 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.

Coreness: от одного бота к сотням — self-hosted open-source платформа для AI-агентов