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

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

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

Репозиторий: github.com/Vensus137/Coreness

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

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

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-ответом (как на диаграмме):

1. Telegram Bot API отправляет webhook с новым сообщением

2. Event Processor парсит Update асинхронно и создаёт Task

3. Scenario Engine ищет триггер в YAML-сценариях и находит подходящий

4. 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, отправляет ответ пользователю

5. 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)

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:

1. Открываем master_bot

2. Отправляем /tenant

3. Вводим ID тенанта (101)

4. Нажимаем "Синхронизация"

Результат

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

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

• 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: "✅ Платеж успешно обработан! Премиум активирован."

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

1. Пользователь отправляет /buy → создаётся инвойс

2. Пользователь нажимает "Оплатить" → Telegram отправляет pre_checkout_query

3. Бот подтверждает платеж через confirm_payment (в течение 10 секунд)

4. Telegram обрабатывает платеж → отправляет payment_successful

5. Бот отмечает инвойс как оплаченный и активирует подписку

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

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

Стек

• 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-запросы.

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

Каждая фича — отдельный плагин в папке 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

• Telegram-канал: t.me/coreness

• Связь с автором: @vensus137

Coreness — Create. Automate. Scale.