🧠 Cogni-Vault

AI-архивариус знаний для групповых чатов Telegram
_{Тихо слушает · Фильтрует шум · Извлекает факты · Отвечает на вопросы через RAG}

💡 Что такое Cogni-Vault?

Cogni-Vault — Telegram-бот, работающий как тихий архивариус знаний для групповых чатов. Он читает сообщения от всех участников, использует многоуровневый AI-пайплайн для фильтрации шума и извлечения полезных фактов, сохраняет их как векторы в PostgreSQL+pgvector и отвечает на вопросы авторизованных пользователей через RAG (Retrieval-Augmented Generation).

Ключевой принцип: Бот слушает всех, но отвечает только пользователям из вайтлиста.

✨ Возможности

� Чем Cogni-Vault отличается от типичных RAG-ботов

Большинство open-source Telegram-ботов с RAG работают по простой схеме: входящее сообщение → нарезка на чанки → сохранение в вектор-БД. Cogni-Vault — это архитектура когнитивной обработки, а не скрипт автоматизации.

Cogni-Vault не просто сохраняет сообщения — он их осмысляет. Входящий текст проходит через фильтрацию, извлечение фактов, тегирование и векторизацию перед сохранением в базу знаний.

�🏗️ Архитектура

┌──────────────────────────────────────────────────────────────────┐
│                      ГРУППОВОЙ ЧАТ TELEGRAM                      │
│                                                                  │
│  Юзер А: «Конференция 15 мая в Хилтоне»                          │
│  Юзер Б: «лол класс»                                             │
│  Юзер В: «Дедлайн по заявкам — 30 апреля»                        │
└─────────┬────────────────────────────────────────────────────────┘
          │
          ▼
┌──────────────────────────────────────────────────────────────────┐
│                         COGNI-VAULT БОТ                          │
│                                                                  │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐                  │
│  │  Debounce  │─▶│  Загрузка  │─▶│  Вайтлист  │                  │
│  │ Middleware │  │ User из БД │  │ Middleware │                  │
│  └────────────┘  └────────────┘  └─────┬──────┘                  │
│                                        │                         │
│  ┌─────────────────────────────────────▼────────────────────┐    │
│  │                МНОГОУРОВНЕВЫЙ AI-ПАЙПЛАЙН                │    │
│  │                                                          │    │
│  │  ┌──────────┐ ┌────────┐ ┌─────────┐ ┌────────────┐      │    │
│  │  │ Сплиттер │▶│ Фильтр │▶│ Тезис,  │▶│ Векториз.  │      │    │
│  │  │ сообщений│ │ SAVE / │ │ теги,   │ │ (Embedding │      │    │
│  │  │(DumbSm.) │ │  SKIP  │ │ даты    │ │   Model)   │      │    │
│  │  └──────────┘ │ (Dumb) │ │(DumbSm.)│ └─────┬──────┘      │    │
│  │               └────────┘ └─────────┘       │             │    │
│  └────────────────────────────────────────────┴─────────────┘    │
│                                               │                  │
│  ┌────────────────────────────────────────────▼─────────────┐    │
│  │                  POSTGRESQL + PGVECTOR                   │    │
│  │  ┌────────┐  ┌───────────┐  ┌────────┐  ┌──────────┐     │    │
│  │  │ users  │  │ knowledge │  │ chats  │  │ vectors  │     │    │
│  │  │        │  │  entries  │  │        │  │(pgvector)│     │    │
│  │  └────────┘  └───────────┘  └────────┘  └──────────┘     │    │
│  └──────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │                  RAG-ПАЙПЛАЙН ЗАПРОСОВ                   │    │
│  │                                                          │    │
│  │  @mention ──▶ Embed ──▶ Гибридный ──▶ Smart LLM          │    │
│  │              (L2)       поиск         (L4 Smart)         │    │
│  │                                          │               │    │
│  │                                          ▼               │    │
│  │                              Форматированный ответ       │    │
│  └──────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────┘

Уровни AI-моделей

🚀 Быстрый старт

Предварительные требования

• Python 3.11+
• PostgreSQL 16 с pgvector (или Docker)
• Токен Telegram-бота от @BotFather
• OpenAI-совместимый API-эндпоинт и ключ

Вариант 1: Docker Compose (рекомендуется)

Вариант 2: Локальная разработка

⚙️ Конфигурация

Cogni-Vault использует каскадную конфигурацию из трёх уровней (в порядке приоритета):

1. Переменные окружения /
   .env
   — высший приоритет, перекрывают всё
2. config.yaml
   — базовая структура и значения
3. Значения по умолчанию — встроены в Pydantic-схему

Для вложенных ключей используйте разделитель

Совет: Скопируйте

.env.example

в

.env

— там перечислены все доступные параметры с описаниями и значениями по умолчанию.

📁 Структура проекта

cogni-vault/
├── src/cogni_vault/
│   ├── main.py                  # Бутстрап и запуск приложения
│   ├── health.py                # HTTP-эндпоинты health/ready/metrics
│   ├── metrics.py               # Реестр метрик Prometheus
│   ├── shutdown.py              # Координатор graceful shutdown
│   ├── logger.py                # Конфигурация structlog (JSON)
│   │
│   ├── config/                  # Pydantic Settings (YAML + ENV каскад)
│   │
│   ├── bot/                     # Слой Telegram
│   │   ├── handlers.py          # Обработчики сообщений и команд
│   │   ├── middleware.py        # Загрузка User, проверка вайтлиста
│   │   ├── message_debouncer.py # Буферизация быстрых сообщений
│   │   └── debounce_middleware.py
│   │
│   ├── database/                # Слой данных
│   │   ├── models/              # User, Chat, KnowledgeEntry
│   │   ├── models_def.py        # SQLAlchemy ORM определения
│   │   └── session.py           # Async engine и session factory
│   │
│   ├── services/                # Бизнес-логика
│   │   ├── ai/                  # LLM-сервисы
│   │   │   ├── dumb_model.py           # L1 — бинарный фильтр
│   │   │   ├── dumb_smart_model.py     # L3 — извлечение фактов, сплит
│   │   │   ├── embedding_model.py      # L2 — векторизация
│   │   │   ├── smart_model.py          # L4 — RAG-ответы
│   │   │   ├── stt_service.py          # Whisper STT
│   │   │   ├── ocr_service.py          # OCR изображений
│   │   │   ├── file_parser_service.py  # Парсинг документов
│   │   │   ├── link_scraper_service.py # Извлечение контента из URL
│   │   │   └── factory.py              # LLM-роутер и фабрика
│   │   ├── knowledge_service.py        # CRUD для записей знаний
│   │   ├── query_service.py            # Оркестрация RAG-запросов
│   │   ├── formatted_query_service.py  # Форматирование для Telegram
│   │   └── hybrid_search_service.py    # Векторный + ключевой поиск
│   │
│   └── rag/                     # Компоненты RAG-пайплайна
│
├── tests/                       # 394+ тестов (pytest + pytest-asyncio)
├── alembic/                     # Миграции базы данных
├── docs/                        # Дополнительная документация
├── docker-compose.yml           # App + PostgreSQL (pgvector)
├── Dockerfile                   # Multi-stage production сборка
└── config.yaml                  # Конфигурация по умолчанию

🧪 Разработка

Запуск тестов

Линтинг и форматирование

Миграции базы данных

📊 Наблюдаемость

Health-эндпоинты (порт 8080)

Метрики Prometheus

Graceful Shutdown

При получении

1. Сброс дебаунс-буферов
2. Остановка поллинга бота и закрытие сессии Telegram
3. Закрытие всех подключений LLM-клиентов
4. Уничтожение движка базы данных
5. Остановка HTTP-сервера health

Каждый колбэк имеет таймаут 10 секунд. Работает на Unix и Windows.

🐳 Docker

Сборка и запуск

Сервисы:

Dockerfile использует multi-stage сборку:

• Builder — установка зависимостей и пакета
• Production — копирование только установленных пакетов, запуск от non-root пользователя
  appuser
  , порт 8080

🔄 CI/CD

CI работает на GitVerse (

📝 Технологический стек

📜 Лицензия

BSD — свободное использование, модификация и распространение в любых целях, включая коммерческие. Подробности в LICENSE.