DEV Community: Anatoly (Vensus)

Coreness Flow: Event-Driven AI Agent — No Cloud, No Code

Anatoly (Vensus) — Wed, 11 Mar 2026 11:37:00 +0000

Most AI assistants are just a chat: you type a question, you get an answer. Coreness Flow was built differently from the start. It's a local Windows application where an agent reacts to events — a message, a webhook, a cron schedule — and executes chains of actions defined in YAML. Want to change the agent's behavior? Edit the config, not the code. No cloud component: everything runs on your own machine.

Repository: github.com/Vensus137/Coreness-Flow

Note: The project and most of its documentation are currently in Russian.

The Idea: Not "Question–Answer", But "Event → Chain"

A standard AI chat is a synchronous loop: the user writes something, the model responds. Coreness Flow breaks that loop.

The central unit here is an event. A chat message arrives — that's an event. A cron fires at 9 AM — event. A webhook comes in from an external service — also an event. The scenario engine finds the matching scenario by trigger and executes a chain of steps: reads data, calls an LLM, searches the knowledge base, sends a reply. The same mechanism handles all sources.

This enables workflows that in a regular chatbot you'd have to implement in code — here everything is described in YAML: a daily digest on a schedule, an automatic webhook response, a reaction to a specific command with branching logic.

Agent behavior is defined by config and scenarios, not code.

Architecture: Three Layers, One Bus

The application is split into three layers that have no direct knowledge of each other — they communicate only through the API Bus.

UI Layer — Electron + React. The frontend is purely a view layer. It connects to the Python backend via WebSocket, sends actions, and receives events. No business logic in React — only rendering and bus calls.
Backend Layer — Python plugins. All logic lives here: message processing, LLM calls, database access, RAG, scheduler. Each plugin is isolated and communicates with others only through the API Bus.
API Bus — a unified contract between all participants. Two modes:
- call — blocking call with a result (use when the next step depends on the outcome)
- call_nowait — fire-and-forget background execution (for long chains, external requests)

Every call returns a unified response format: { result, error, response_data }. The scenario engine treats them all the same — it calls actions by name and reads the result.

Why This Separation

The most common architectural mistake in apps like this — UI knows about the database, business logic calls components directly. Add a new feature and you're doing surgery in three places at once.

In Coreness Flow, the UI has no idea which plugins are loaded. On startup, the frontend asks the backend for a description of what plugins contribute to the interface, then builds the screen from that data. A new plugin means a new tab — with zero frontend changes.

Add a plugin folder — the interface adapts automatically.

Lifecycle: How the App Starts


Electron main process
↓ spawn
Python backend
↓
API Bus initializes
↓
Container scans plugins/, merges configs, creates instances
↓
Heavy plugin initialization (splash shows progress)
↓
Plugin background tasks
↓
WebSocket server starts
↓
Main window opens, frontend connects
↓
Collect plugin descriptions → UI builds sidebar, tabs, settings

Each stage is isolated. If a plugin crashes during initialization, the rest continue loading. Graceful shutdown: plugin and worker timeouts are set in app.json; the app closes cleanly on exit or update.

Plugins: VS Code-style, But for a Desktop App

The plugin system is one of the most interesting parts of the architecture. The idea is borrowed from VS Code: a plugin doesn't just add backend logic — it declares its contribution to the application via config.json.

Each plugin is a folder with two key files: config.json (what the plugin does and what it adds to the UI) and a Python module (how it's implemented). On startup, the container recursively scans plugins/ and loads every folder that contains a config.json. The folder name becomes the plugin identifier. No registry, no explicit module list in the core code.

config.json — The Heart of a Plugin

The config describes four things:

metadata — plugin name and description.
settings — settings schema with defaults. On startup, the container merges defaults from the config with user overrides from user_settings.json. The plugin always receives the final merged config.
actions — the list of actions the plugin registers in the API Bus. Each action has a defined input (payload schema) and output.
contributes — what the plugin adds to the UI. This is the most interesting part.

Python class methods whose names match keys in actions automatically become call handlers — no explicit registration needed. Declare an action in the config and implement a method with the same name — the engine wires them together on plugin load.

Config + method with the same name — a binding with no explicit registration.

Contributes: UI From Config

Four contribution points:

Point	What it adds
`workspace`	A tab in the main content area with a widget (list, settings form, etc.)
`settings`	A section on the shared "Settings" tab
`sidebar`	An item in the sidebar (click triggers an action)
`menus`	Items in dropdown menus

The widget type for a tab is described with a descriptor: settingsForm, list — the frontend renders content without any custom code. List columns, data source via action, form fields — all in the plugin's JSON config. The "Vector Store" tab with a chunk list and delete buttons is defined in the plugin like this:

"contributes": {
  "workspace": {
    "id": "vector_store_admin",
    "label": "Vector Store",
    "title": "Vector Store",
    "content": {"widget": "vectorStoreAdmin"}
  }
}

vectorStoreAdmin is a built-in widget type registered in the frontend; the plugin only references it by name. Not a single line of React in the plugin — just config.

This creates a clear separation of concerns: a backend developer writes the plugin and its config, the UI layer adapts itself. Want to remove a tab? Delete the plugin folder. Want to rename it? Change label in the config.

Hot Reload for Settings

A nice touch: when a user changes settings in the UI, the backend notifies the affected plugin — it recreates clients and clears caches without restarting the app. Change an API key or model — the plugin picks it up immediately.

Scenarios: Orchestration Without Code

If plugins are services with actions, scenarios are the way to orchestrate those actions without writing code. All scenarios live in YAML files in config/scenarios/. The engine picks them up recursively from all subdirectories. You can organize them however you like: commands/, system/, scheduled/ — scenario names are global: any scenario can call another by name.

Basic structure:

daily_report:
  schedule: "0 9 * * *"   # Every day at 9:00
  step:
    - action: "get_storage"
      params:
        group_key: "report_config"
        _response_key: "config"
    - action: "completion"
      params:
        prompt: "Generate a morning digest. Context: {_cache.config}"
        model: "{_cache.config.model}"
    - action: "send_chat_message"
      params:
        text: "{_cache.response}"

Each step is a plugin action call. The result is placed in _cache under the key _response_key. The next step reads data via the {_cache.key} placeholder.

Placeholders — Lightweight Templating

Placeholders work in all step parameters and support a modifier chain:

{event_text} — the event's text content
{_cache.system.routing_model} — a nested field from the cache
{now|format:datetime} — current time with formatting
{_cache.field|fallback:default} — value with a default if the field is empty
{_cache.result|exists} — boolean: whether the field exists

This enables flexible chains without any Python code — just value substitution through templates.

Triggers: From Simple to Complex

The simplest trigger form — event type plus text:

trigger:
  - event_type: "message"
    event_text: "/help"

The complex form — a condition field with an expression in a mini-language (operators: ==, ~ for "contains", regex, is_null, etc.; fields via $event_text, $event_type):

trigger:
  - event_type: "message"
    condition: "$event_text ~ '/'"

Multiple triggers in the list work as OR. Fields within a single trigger work as AND. No need to duplicate a scenario for every variant — just add a trigger to the list.

Transitions and Branching

After a step, you can define a transition — a list of rules: based on the action result (action_result: success, error, etc.), a transition is executed (transition_action and optionally transition_value). For example, jumping to another scenario:

- action: "search_chunks"
  params:
    query: "{event_text}"
    _response_key: "rag_result"
  transition:
    - action_result: "success"
      transition_action: "jump_to_scenario"
      transition_value: "step_with_rag"
    - action_result: "error"
      transition_action: "jump_to_scenario"
      transition_value: "step_without_rag"

Found something in RAG — go to one scenario; not found — go to another. All in config.

Step chains and branching — in YAML, no code.

A typical utility scenario: fetch a document by URL, split it into chunks, store in the vector database; on error — transition to an error-handling scenario.

Configuration: Merging Without Magic

The configuration schema is intentionally simple and uniform throughout:

App defaults — config/app.json
Plugin defaults — the settings section in the plugin's config.json
User overrides — %APPDATA%\CorenessFlow\user_settings.json (changed keys only)

On startup, the container merges defaults with user values and passes the final config to each plugin. Secrets and API tokens are stored in SQLite in %APPDATA% — they never end up in the repository.

The same config.json format is used for both the application and every plugin — the container code is unified, and documentation stays consistent.

Storage: Key–Value for Agent Configuration

The database plugin gives scenarios a simple key–value store with grouping: group_key + key → value. But the more interesting part: initial data is defined directly in YAML files in config/storage/ and synchronized into SQLite on startup.

This makes agent behavior configurable without editing scenarios. The router's system prompt, available tools list, model parameters, limits — all stored in storage, scenarios read this data at runtime. Changing the model for simple requests means editing storage, not YAML scenarios.

Agent Routing: How One Request Becomes a Chain of Decisions

Agent routing in Coreness Flow is not a built-in core function — it's a set of system scenarios layered on top of the general mechanism. The user sees: sent a message → "Processing..." → response. Behind the scenes — a chain of several scenarios and multiple LLM calls.

Message Processing Pipeline

When a chat message arrives, the following sequence runs:

Load context — settings are read from storage: system prompt, list of tools and response scenarios, step limit.
Assemble history — chat history is fetched with a size limit; relevant RAG fragments are optionally injected.
Routing — an LLM request with the prompt and tool descriptions. The model decides: invoke one of the tools (e.g., knowledge base search) or generate a direct response.
Execution — if a tool is selected, the corresponding scenario runs, then routing again (loop until step limit).
Finalization — a final model request, and the response is sent to the chat.

New tool = a description in the config + a scenario file; no core changes.

Tools are just YAML scenarios: adding a new one means describing it in the storage config and adding a scenario file. The application core is untouched.

Local RAG: No Servers, No Cloud

The vector store in Coreness Flow is a separate plugin with several key design decisions.

BGE-M3 in ONNX Format, INT8 Quantization

A multilingual model that generates both dense and sparse vectors simultaneously. The model runs via ONNX Runtime — no PyTorch, no CUDA. INT8 quantization reduces memory consumption by roughly 4× compared to float32 with minimal quality loss. Runs on a regular CPU.

Qdrant in Embedded Mode

Qdrant runs inside the application process and persists data to disk. No separate service, no ports, no Docker needed.

Hybrid Search with RRF

BGE-M3 produces both dense vectors (semantics) and sparse vectors (keywords). Searching across both types and merging results via Reciprocal Rank Fusion delivers better quality than semantic-only search — especially for queries with specific terms and proper nouns.

In scenarios this is two actions: add_chunks for indexing and search_chunks for retrieval. The search result is placed in _cache and substituted into the next step's prompt. Documents never leave the machine.

Model Loading and the Splash Screen

BGE-M3 is a heavy model, and loading it on startup requires a dedicated solution. It loads before the main window is shown: the user sees a splash screen with initialization progress; the main window opens only when everything is ready. No frozen UI.

Async Without the Pain

Actions in the API Bus execute in a worker pool — separate threads with their own event loop. The number of workers is configurable. This means a long LLM call doesn't block processing of another incoming event.

call_nowait is particularly useful. You kick off a long scenario chain, don't wait for it to finish, and continue. The result arrives as an event in the UI. This is how the entire chat works: the user sends a message, the backend launches the chain via call_nowait, the UI shows a loading indicator and never blocks.

Plugins subscribe to bus events. This enables reaction to any system events without direct dependencies between plugins.

Project Structure

Coreness-Flow/
├── run_backend.py          # Backend entry point
├── app/
│   ├── runtime/
│   │   ├── container.py    # Plugin scanning, config merging, instantiation
│   │   ├── api_bus.py      # Bus: actions, events, workers
│   │   └── ...
│   ├── settings.py         # Config loading and merging
│   └── ws_server.py        # WebSocket for the frontend
├── frontend/               # Electron + React
├── plugins/
│   ├── core/               # Core modules: chats, database, ai_service, vector_store, ...
│   ├── base/               # Non-critical plugins
│   └── extensions/         # Custom extensions
└── config/
    ├── app.json            # App defaults
    ├── scenarios/          # YAML scenarios
    └── storage/            # Initial storage data

core/ contains the foundation: chats, database, LLM calls, vector store, scenario engine. base/ holds additional plugins — the app runs without them. extensions/ is where you put your own.

Quick Start

From source (Python 3.11, Node.js, Windows):

pip install -r requirements.txt
cd frontend && npm install && cd ..
.\scripts\run-dev.ps1

Backend and window start with a single command. In dev mode: hot reload on config and plugin code changes.

From releases: a Windows installer is available under Releases — no Python or Node needed on the target machine.

After the first launch: set your AI provider in settings (any OpenAI-compatible API), optionally load documents into the vector store, and configure storage to fit your needs.

Stack

Component	Technology
Frontend	Electron + React
Backend	Python 3.11, async/await
UI ↔ Backend	WebSocket + API Bus
LLM	Any OpenAI-compatible API (OpenRouter, etc.)
RAG	BGE-M3 ONNX INT8 + Qdrant embedded
Storage	SQLite + JSON (config) + YAML (scenarios, storage)
Build	Electron Builder + Python backend

Key Design Decisions

What sets Coreness Flow apart:

Plugins without a registry — a folder with a config and module; the container picks it up on startup; unified contract for everything.
UI from config — plugins declare tabs, settings, menu items; the frontend assembles the UI from this data, no plugin list in code.
Scenarios instead of code — action orchestration in YAML: triggers, steps, result-based transitions; the engine calls actions by name.
Local RAG — embeddings and vector store on your own machine, ONNX and Qdrant in-process, offline.
Events and bus — plugins communicate only through the API Bus and subscribe to events; no direct calls between modules.

Build AI-Powered Telegram bots without code: Introducing Coreness

Anatoly (Vensus) — Tue, 10 Feb 2026 10:00:00 +0000

Hey DEV community! 👋

This is my first post here, so a quick intro: I'm a developer who got tired of rebuilding the same Telegram bot infrastructure again and again. Each new bot meant redoing webhooks, storage, admin tooling, and deployment—or paying for SaaS products with limited flexibility.

I wanted a self-hosted solution where bot behavior is easy to change without rewriting code every time. So I built Coreness — an event-driven platform for deploying AI-powered Telegram bots using declarative YAML scenarios. And now I'm making it open source.

GitHub: https://github.com/Vensus137/Coreness
Documentation: docs.coreness.tech

Note on language: The project supports English (docs, code, tooling). You may still run into occasional inaccuracies or mixed-language bits.

The Problem

If you've ever built Telegram bots (especially more than one), you probably recognize these pain points:

Rebuilding the same basics every time: webhook handling, storage, user state, admin utilities
SaaS limitations: you get convenience, but you're locked into someone else’s feature set and pricing
Scaling overhead: multiple bots often become multiple deployments, multiple databases, multiple headaches
AI integration friction: wiring LLMs, context management, and RAG tends to become a project of its own

Coreness is the infrastructure layer I wanted: one platform instance that can run multiple isolated bots, while still being configurable enough for real-world scenarios.

Introducing Coreness

Coreness is a multi-tenant platform where you describe bot behavior in YAML, and the platform handles execution, storage, and integrations. A single server instance can run multiple isolated tenants (bots), each with its own configuration and data.

What you get:

🎯 YAML-based scenarios — no code, just configuration
🏢 Built-in multi-tenancy — complete data isolation via PostgreSQL Row-Level Security
🤖 AI integration — OpenAI, Anthropic, Google, DeepSeek support via aggregators
📚 RAG out of the box — vector search with pgvector
⏰ Scheduled scenarios — cron-style automation
🔌 Plugin architecture — extend features cleanly
💳 Payment handling — Telegram Stars and other providers

How It Works

Instead of writing code, you describe bot behavior declaratively. Here's a simple bot that responds to /start:

start:
  trigger:
    - event_type: "message"
      event_text: "/start"

  step:
    - action: "send_message"
      params:
        text: |
          👋 Hello, {first_name}!

          Welcome to my bot!
        inline:
          - [{"📋 Menu": "menu"}, {"ℹ️ Help": "help"}]

menu:
  trigger:
    - event_type: "callback"
      callback_data: "menu"

  step:
    - action: "send_message"
      params:
        text: "Choose an action:"
        inline:
          - [{"🤖 About": "about"}]
          - [{"🔙 Back": "start"}]

What's happening here:

trigger defines when the scenario runs (command or button press)
step is a sequence of actions executed in order
{first_name} is a placeholder resolved from user/context data
inline defines Telegram inline buttons

The platform automatically handles webhook processing, database storage, and user context. You just describe what should happen.

RAG in Action

Want your bot to answer questions using a knowledge base? Here’s what a basic RAG flow can look like:

ask_question:
  trigger:
    - event_type: "message"

  step:
    # Search for relevant context
    - action: "search_embedding"
      params:
        query_text: "{event_text}"
        document_type: "knowledge"
        limit_chunks: 3
        min_similarity: 0.7

    # Generate AI response with context
    - action: "completion"
      params:
        prompt: "{event_text}"
        system_prompt: "You are a helpful assistant. Answer based on provided context."
        rag_chunks: "{_cache.chunks}"
        model: "gpt-4o-mini"

    # Send response
    - action: "send_message"
      params:
        text: "{_cache.response_completion}"

In this flow, the system:

Retrieves relevant chunks from the vector store
Builds a context payload for the LLM
Sends a completion request to the selected model
Returns a contextual response to the user

The key idea: you compose RAG behavior by chaining actions, not by rewriting RAG plumbing for each project.

Multi-tenancy Magic

The platform provides automatic data isolation using PostgreSQL Row-Level Security. Each tenant gets their own sandbox — settings, knowledge bases, prompts — everything is isolated at the database level.

RLS automatically filters queries by tenant_id, so you never accidentally access another tenant's data. No need to add WHERE tenant_id = ... to every query.

Adding a new bot is simple:

Create a folder like config/tenant/tenant_101/
Add bots/telegram.yaml with bot token (the bots/ folder can hold configs for different bot types)
Add your YAML scenarios
Sync via GitHub or using the Master Bot (a built-in management interface, similar to @botfather, that lets you control tenants, sync configs, and manage the platform from Telegram)

Done. The platform picks it up automatically and starts processing events for that bot.

Getting Started (5-Minute Setup)

Here's how to get your first bot running:

Step 1: Deploy the Platform

Coreness includes the Core Manager utility for deployment and updates. It configures the environment, database, and containers.

# Clone repository
git clone https://github.com/Vensus137/Coreness.git
cd Coreness

# Run Core Manager
python tools/core_manager/core_manager.py

On first run the utility will ask for:

Environment (test / prod)
Deployment mode (docker / native) — native is often easier on Windows; docker is typical on Linux and servers
Interface language (English / Русский)

Settings are saved in config/.version. The menu then offers: system update from GitHub (with migrations and backup), database operations (migrations, backup, restore), utility self-update, and language switch.

Step 2: Create a Tenant

Create config/tenant/tenant_101/bots/telegram.yaml:

bot_token: "YOUR_BOT_TOKEN_FROM_BOTFATHER"
is_active: true

Step 3: Configure Scenario

Create config/tenant/tenant_101/scenarios/start.yaml:

start:
  trigger:
    - event_type: "message"
      event_text: "/start"

  step:
    - action: "send_message"
      params:
        text: |
          👋 Hello, {first_name}!

          This is a bot powered by Coreness.
        inline:
          - [{"📋 Menu": "menu"}, {"ℹ️ Help": "help"}]

Step 4: Sync

If using GitHub sync:

git add config/tenant/tenant_101/
git commit -m "Add tenant 101"
git push
# Webhook automatically syncs changes

Or manually via Master Bot:

Open master_bot
Send /tenant
Enter tenant ID (101)
Click "Sync"

That's it! Your bot is live and responding to commands.

Bonus: Adding Payments

Want to monetize your bot? Here's how to add Telegram Stars payments:

buy_premium:
  trigger:
    - event_type: "message"
      event_text: "/buy"

  step:
    - action: "create_invoice"
      params:
        title: "Premium Subscription"
        description: "Access to premium features for 1 month"
        amount: 100  # 100 stars
        currency: "XTR"

handle_pre_checkout:
  trigger:
    - event_type: "pre_checkout_query"

  step:
    - 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: "✅ Payment successful! Premium activated."

The entire payment flow is declarative — no manual payment handling code needed.

Under the Hood

Tech Stack

Python 3.11+ with direct Telegram Bot API integration (no aiogram — fewer dependencies, better performance)
PostgreSQL 16+ with pgvector extension for RAG (or SQLite for simplified version)
Docker + docker-compose for deployment
LLM aggregators for model access (OpenAI, Anthropic, Google, DeepSeek via OpenRouter, Azure OpenAI)

Why no aiogram? Direct work with Telegram Bot API via aiohttp saves resources, runs faster, and has fewer dependencies. All you need is JSON parsing and HTTP requests.

Architecture

Coreness is built on event-driven architecture with clear layer separation:

Telegram → Event Processor → Scenario Engine → Step Executor → Services → Response

Each service is self-contained and communicates through events. No tangled dependency web, just clean vertical slices of functionality.

Plugin System:

Every feature is a separate plugin in the plugins/ folder. Need integration with an external API? Just write a new plugin and drop it in.

plugins/
├── utilities/          # Helper utilities
│   ├── foundation/     # Core (logger, plugins_manager)
│   ├── telegram/       # Telegram utilities
│   └── core/           # Infrastructure (event_processor, database)
└── services/           # Business services
    ├── hub/
    │   ├── telegram/   # Bot management (Telegram)
    │   └── tenant_hub/ # Tenant management
    └── ai_service/     # AI and RAG

Plugins are isolated and communicate via events. Add a new plugin — the DI container automatically discovers and wires it, and the service registers its actions through action_hub.

Performance

Async processing via asyncio — all operations are non-blocking
Caching of data and settings — reduces DB load
Vector search optimization with HNSW indexes (pgvector) — fast search even on large datasets
Parallel processing — bots can handle multiple events simultaneously
Direct Telegram API — no middleware overhead

This matters at scale. One server can handle dozens of bots simultaneously without performance degradation.

Security

Row-Level Security for data isolation — impossible to accidentally access another tenant's data
Validation via Pydantic — all input parameters checked against schemas
Secrets in environment variables — tokens and keys not stored in code
Automated DB backups with configurable interval
Flexible access control — configure read-only users with access to specific tenants

What's Next

I'm making Coreness open source to grow it with the community. Here's what's on the roadmap:

Extended RAG capabilities — support for files (PDF, DOCX), improved document processing
More ready-to-use plugins — integrations with popular APIs
Simplified Master Bot — better tenant management interface
Telegram Mini App — additional management features through Telegram Mini App

Try It Out

I built Coreness because I needed it for my own projects, and I'm betting others face the same problems. If you're tired of rebuilding bot infrastructure or paying for limited SaaS solutions, give it a try.

GitHub: https://github.com/Vensus137/Coreness
Documentation: docs.coreness.tech
Contact me: @vensus137

⭐ Star the repo if you find it useful

💬 Open issues or PRs — all feedback helps improve the project

📢 Share with others who might benefit

I'd love to hear your thoughts and contributions! 🚀

Coreness — Create. Automate. Scale.