🧠 Cogni-Vault

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

Python 3.11+ · aiogram 3 · PostgreSQL 16 + pgvector · SQLAlchemy 2.0 · Docker

v0.1.5 · 394+ тестов · 73% покрытие · BSD лицензия

--- ## 💡 Что такое Cogni-Vault? Cogni-Vault — Telegram-бот, работающий как **тихий архивариус знаний** для групповых чатов. Он читает сообщения от всех участников, использует многоуровневый AI-пайплайн для фильтрации шума и извлечения полезных фактов, сохраняет их как векторы в PostgreSQL+pgvector и отвечает на вопросы авторизованных пользователей через RAG (Retrieval-Augmented Generation). > **Ключевой принцип:** Бот слушает *всех*, но отвечает только *пользователям из вайтлиста*. --- ## ✨ Возможности

### 📥 Пайплайн записи (Write) - **Тихий слушатель** — фиксирует полезные факты от всех участников чата - **Настраиваемая модерация** — 4 уровня фильтрации: `strict` / `moderate` / `relaxed` / `off` - **Разбор списков** — определяет списки и сохраняет каждый пункт отдельно - **Извлечение дат** — определяет даты событий из сообщений - **Голосовые** — транскрипция через Whisper STT - **Распознавание изображений** — OCR для извлечения текста из фото - **Парсинг файлов** — поддержка PDF, DOCX, TXT - **Сбор ссылок** — извлечение контента из URL - **Дедупликация** — предотвращение сохранения дубликатов

### 📤 RAG-пайплайн (Read) - **Гибридный поиск** — векторное сходство + ключевые слова - **Умные ответы** — LLM генерирует ответы с контекстом - **Указание источников** — показывает, откуда взята информация - **Даты событий** — отображает 📅 даты начала/окончания - **Поддержка @mention** — отвечает при упоминании в группах - **Личные сообщения** — вайтлист-пользователи могут писать в ЛС - **Словарь терминов** — подключение доменных глоссариев

### 🔐 Управление доступом - **Super Admin** — полный контроль, задаётся через ENV - **Admin** — может добавлять пользователей в вайтлист - **Whitelisted User** — может запрашивать базу знаний - **Contributor** — сообщения записываются, доступа к запросам нет

### ⚙️ Эксплуатация - **Health-эндпоинты** — `/health`, `/ready`, `/metrics` - **Метрики Prometheus** — 14 предзарегистрированных метрик - **Graceful shutdown** — упорядоченное завершение с таймаутами - **CI/CD** — линт, тайпчек, тесты с покрытием - **Docker** — multi-stage сборка, non-root пользователь

--- ## � Чем Cogni-Vault отличается от типичных RAG-ботов Большинство open-source Telegram-ботов с RAG работают по простой схеме: входящее сообщение → нарезка на чанки → сохранение в вектор-БД. Cogni-Vault — это **архитектура когнитивной обработки**, а не скрипт автоматизации. | Характеристика | Типичный RAG-бот | Cogni-Vault | |---------------|-----------------|-------------| | **AI-пайплайн** | 1 модель на все задачи | 6 специализированных моделей по тирам (L1–L4, OCR, STT) | | **Фильтрация шума** | Нет или примитивная (по длине) | L1 Dumb Model — бинарный AI-фильтр SAVE/SKIP | | **Обработка данных** | Сырое сохранение текста | L3 DumbSmart — извлечение фактов, тегов, дат, разбор списков | | **Поиск** | Только векторный | Гибридный: вектор + ключевые слова | | **Форматы ввода** | Только текст | Текст, голос (STT), изображения (OCR), PDF, DOCX, ссылки | | **Дедупликация** | Нет | Content-hash дедупликация | | **Группировка сообщений** | Нет | Debouncer: буферизация быстрых сообщений | | **Управление доступом** | Токен бота | 4-уровневая ролевая модель (Super Admin → Contributor) | | **Мониторинг** | Нет | Health/Ready/Metrics, 14 метрик Prometheus | | **Завершение** | `kill -9` | Graceful shutdown с LIFO-порядком и таймаутами | | **Провайдеры** | 1 API-ключ, 1 модель | Мульти-провайдер: разные модели от разных API | | **Запуск** | Нужна интеграция | Plug & play: `docker compose up` — и бот в чате | > **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-моделей | Уровень | Назначение | Стоимость | Примеры моделей | |---------|-----------|-----------|-----------------| | 🟢 **L1 — Dumb** | Бинарный фильтр: SAVE или SKIP | Минимальная | T-lite, Llama 3.2 1B | | 🔵 **L2 — Embedding** | Векторизация текста для хранения и поиска | Низкая | Qwen3-Embedding-0.6B | | 🟡 **L3 — DumbSmart** | Извлечение фактов, тезисов, тегов, дат; разбор списков | Средняя | GigaChat3-10B | | 🔴 **L4 — Smart** | RAG-ответы с поддержкой tool calling | Высокая | GLM-4.7-Flash, GPT-4o | | 🟣 **OCR** | Извлечение текста из изображений | Средняя | DeepSeek-OCR-2 | | ⚪ **Whisper** | Транскрипция речи в текст | Средняя | whisper-large-v3 | --- ## 🚀 Быстрый старт ### Предварительные требования - Python 3.11+ - PostgreSQL 16 с [pgvector](https://github.com/pgvector/pgvector) (или Docker) - Токен Telegram-бота от [@BotFather](https://t.me/BotFather) - OpenAI-совместимый API-эндпоинт и ключ ### Вариант 1: Docker Compose (рекомендуется) ```bash # Клонируем репозиторий git clone https://gitverse.ru/lid/cogni-vault.git cd cogni-vault # Конфигурация cp config.yaml config.local.yaml # Отредактируйте config.local.yaml — укажите токен бота, API-ключи и т.д. # Запуск всего стека docker compose up --build -d # Миграции БД docker compose exec app alembic upgrade head ``` ### Вариант 2: Локальная разработка ```bash # Клонируем и заходим git clone https://gitverse.ru/lid/cogni-vault.git cd cogni-vault # Виртуальное окружение python -m venv venv venv\Scripts\activate # Windows # source venv/bin/activate # Unix # Установка зависимостей pip install -r requirements-dev.txt # Запуск базы данных docker compose up db -d # Миграции alembic upgrade head # Конфигурация cp config.yaml config.local.yaml # Отредактируйте файл или укажите переменные окружения # Запуск бота python run.py ``` --- ## ⚙️ Конфигурация Cogni-Vault использует **каскадную конфигурацию** из трёх уровней (в порядке приоритета): 1. **Переменные окружения / `.env`** — **высший приоритет**, перекрывают всё 2. **`config.yaml`** — базовая структура и значения 3. **Значения по умолчанию** — встроены в Pydantic-схему Для вложенных ключей используйте разделитель `__`: ```bash DATABASE__URL=postgresql+asyncpg://user:pass@host:5432/dbname BOT__TOKEN=123456:ABC-DEF PROCESSING__FILTER_SENSITIVITY=moderate ``` > **Совет:** Скопируйте `.env.example` в `.env` — там перечислены **все** доступные параметры с описаниями и значениями по умолчанию.

📋 Полный справочник конфигурации (развернуть)

### `database` | Ключ | Тип | Умолчание | Описание | |------|-----|-----------|----------| | `url` | string | `postgresql+asyncpg://...@localhost:5432/cogni_vault` | URL базы данных (async) | | `echo` | bool | `false` | Логирование SQL-запросов | | `pool_size` | int | `10` (1–100) | Размер пула соединений | | `max_overflow` | int | `20` (0–100) | Допустимое превышение пула | ### `bot` | Ключ | Тип | Умолчание | Описание | |------|-----|-----------|----------| | `token` | string | `""` | Токен Telegram-бота | | `super_admin_telegram_id` | int/null | `null` | Telegram ID суперадмина | | `whitelist_chat_ids` | list[int] | `[]` | ID чатов для записи сообщений | | `admins` | list[int] | `[]` | Telegram ID администраторов | ### `providers` Определение одного или нескольких OpenAI-совместимых API-провайдеров: ```yaml providers: default: base_url: "https://foundation-models.api.cloud.ru/v1" api_key: "your_api_key_here" whisper_url: "https://foundation-models.api.cloud.ru/v1/audio/transcriptions" timeout: 30 max_retries: 3 ``` | Ключ | Тип | Умолчание | Описание | |------|-----|-----------|----------| | `base_url` | string | `https://api.openai.com/v1` | Базовый URL API | | `api_key` | string | `""` | API-ключ | | `timeout` | int | `30` (1–300) | Таймаут запроса (секунды) | | `max_retries` | int | `3` (0–10) | Макс. количество повторов | | `retry_base_delay` | float | `1.0` (0.1–10.0) | Базовая задержка между повторами | | `retry_max_delay` | float | `10.0` (1.0–60.0) | Макс. задержка между повторами | | `whisper_url` | string | `https://api.openai.com/v1/audio/transcriptions` | Эндпоинт Whisper STT | ### `ai_models` Каждая модель ссылается на провайдера и указывает свой уровень: ```yaml ai_models: dumb: provider: default model: "t-tech/T-lite-it-1.0" temperature: 0.3 max_tokens: 500 tier: dumb supports_tools: false embedding: provider: default model: "Qwen/Qwen3-Embedding-0.6B" tier: embedding dumb_smart: provider: default model: "ai-sage/GigaChat3-10B-A1.8B" temperature: 0.5 max_tokens: 1000 tier: dumb_smart smart: provider: default model: "zai-org/GLM-4.7-Flash" temperature: 0.7 max_tokens: 4000 tier: smart supports_tools: true ocr: provider: default model: "deepseek-ai/DeepSeek-OCR-2" tier: ocr whisper: provider: default model: "openai/whisper-large-v3" tier: whisper ``` | Ключ | Тип | Умолчание | Описание | |------|-----|-----------|----------| | `provider` | string | `"default"` | Имя провайдера из `providers` | | `model` | string | `"gpt-4"` | Идентификатор модели | | `temperature` | float | `0.7` (0–2) | Температура сэмплирования | | `max_tokens` | int | `2000` (1–8000) | Макс. токенов в ответе | | `tier` | ModelTier | `"dumb"` | Уровень модели (см. Архитектура) | | `supports_tools` | bool | `false` | Поддержка tool calling | | `system_prompt` | string/null | `null` | Кастомный системный промпт | ### `processing` | Ключ | Тип | Умолчание | Описание | |------|-----|-----------|----------| | `process_text` | bool | `true` | Обработка текстовых сообщений | | `process_voice` | bool | `false` | Обработка голосовых (Whisper) | | `process_images` | bool | `false` | Обработка изображений (OCR) | | `process_documents` | bool | `false` | Обработка загруженных документов | | `process_links` | bool | `false` | Обработка URL/ссылок | | `debounce_seconds` | int | `7` (1–30) | Окно дебаунса сообщений | | `max_message_length` | int | `4000` (100+) | Макс. длина обрабат. сообщения | | `embedding_batch_size` | int | `100` (1–1000) | Размер батча для эмбеддингов | | `filter_model` | string | `"dumb"` | Модель для фильтрации | | `processor_model` | string | `"dumb_smart"` | Модель для извлечения фактов | | `filter_sensitivity` | string | `"strict"` | Уровень фильтрации: `strict` / `moderate` / `relaxed` / `off` | ### `knowledge_base` | Ключ | Тип | Умолчание | Описание | |------|-----|-----------|----------| | `vector_dimension` | int | `1536` (1–32768) | Размерность вектора эмбеддинга | | `similarity_threshold` | float | `0.7` (0–1) | Мин. сходство для результатов | | `max_results` | int | `5` (1–100) | Макс. результатов поиска | | `chunk_size` | int | `500` (100–5000) | Размер чанка при нарезке текста | | `chunk_overlap` | int | `50` (0–1000) | Перекрытие между чанками | | `enable_deduplication` | bool | `true` | Включить обнаружение дубликатов | | `dedup_lookback_days` | int | `30` (1–365) | Период поиска дубликатов (дни) | | `dedup_similarity_threshold` | float | `0.85` (0–1) | Порог сходства для дедупликации | | `vector_weight` | float | `0.6` (0–1) | Вес векторного поиска | | `keyword_weight` | float | `0.4` (0–1) | Вес поиска по ключевым словам | ### `logging` | Ключ | Тип | Умолчание | Описание | |------|-----|-----------|----------| | `level` | string | `"INFO"` | DEBUG, INFO, WARNING, ERROR, CRITICAL | | `format` | string | `"json"` | Формат вывода логов | | `include_timestamp` | bool | `true` | Добавлять временную метку | | `include_correlation_id` | bool | `true` | Добавлять correlation ID | ### `term_definitions` Подключение доменных терминов в промпты AI для улучшения контекста: ```yaml term_definitions: enabled: true definitions: ВСОШ: "Всероссийская олимпиада школьников" БВИ: "без вступительных испытаний" ```

🔀 Настройка нескольких провайдеров (развернуть)

Назначение разных моделей разным провайдерам для оптимизации затрат: ```yaml providers: cloudru: base_url: "https://foundation-models.api.cloud.ru/v1" api_key: "cloudru_key" openai: base_url: "https://api.openai.com/v1" api_key: "sk-..." local: base_url: "http://localhost:8000/v1" api_key: "not-needed" ai_models: dumb: provider: local # дешёвая локальная модель для фильтрации model: "llama-3.2-1b" tier: dumb smart: provider: openai # мощная модель для RAG-ответов model: "gpt-4o" tier: smart supports_tools: true embedding: provider: cloudru # эмбеддинги Cloud.ru model: "Qwen/Qwen3-Embedding-0.6B" tier: embedding ``` Все провайдеры должны предоставлять OpenAI-совместимый эндпоинт `/v1/chat/completions`.

--- ## 📁 Структура проекта ``` 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 # Конфигурация по умолчанию ``` --- ## 🧪 Разработка ### Запуск тестов ```bash pytest # Все тесты pytest --cov=src --cov-report=html # С отчётом о покрытии pytest -m "not slow" # Только быстрые тесты pytest -m integration # Интеграционные (нужен PostgreSQL) pytest tests/test_config.py -v # Один файл pytest tests/test_config.py::test_env_override # Один тест ``` ### Линтинг и форматирование ```bash black src/ # Форматирование кода isort src/ # Сортировка импортов flake8 src/ # Линтинг mypy src/ # Проверка типов # Всё сразу mypy src/ && flake8 src/ && black src/ && isort src/ ``` ### Миграции базы данных ```bash alembic revision --autogenerate -m "Описание" # Создать миграцию alembic upgrade head # Применить все ожидающие alembic downgrade -1 # Откатить одну ``` --- ## 📊 Наблюдаемость ### Health-эндпоинты (порт 8080) | Эндпоинт | Метод | Описание | |-----------|-------|----------| | `/health` | GET | Liveness probe — 200, если процесс жив | | `/ready` | GET | Readiness probe — 200, только когда БД доступна | | `/metrics` | GET | Метрики в формате Prometheus | ### Метрики Prometheus

Все 14 метрик

| Метрика | Тип | Описание | |---------|-----|----------| | `messages_received_total` | counter | Всего получено сообщений | | `messages_processed_total` | counter | Сообщений обработано через пайплайн | | `messages_filtered_total` | counter | Отфильтрованных сообщений (SKIP) | | `llm_requests_total` | counter | Всего запросов к LLM API | | `llm_request_duration_seconds` | histogram | Латентность запросов к LLM | | `llm_errors_total` | counter | Ошибок LLM API | | `knowledge_entries_total` | counter | Записей знаний сохранено | | `knowledge_duplicates_total` | counter | Обнаружено дубликатов | | `rag_queries_total` | counter | Всего RAG-запросов | | `rag_query_duration_seconds` | histogram | Латентность RAG-запросов | | `active_debounce_buffers` | gauge | Активных дебаунс-буферов | | `db_session_duration_seconds` | histogram | Длительность сессий БД | | `health_check_total` | counter | Запросов health check |

### Graceful Shutdown При получении `SIGTERM` / `SIGINT` компоненты завершаются в обратном порядке регистрации: 1. Сброс дебаунс-буферов 2. Остановка поллинга бота и закрытие сессии Telegram 3. Закрытие всех подключений LLM-клиентов 4. Уничтожение движка базы данных 5. Остановка HTTP-сервера health Каждый колбэк имеет **таймаут 10 секунд**. Работает на Unix и Windows. --- ## 🐳 Docker ### Сборка и запуск ```bash docker compose up --build -d ``` **Сервисы:** | Сервис | Контейнер | Описание | |--------|-----------|----------| | `app` | `cogni-vault-app` | Бот (ждёт готовности БД) | | `db` | `cogni-vault-db` | PostgreSQL 16 с pgvector | Dockerfile использует **multi-stage сборку**: - **Builder** — установка зависимостей и пакета - **Production** — копирование только установленных пакетов, запуск от non-root пользователя `appuser`, порт 8080 --- ## 🔄 CI/CD CI работает на [GitVerse](https://gitverse.ru) (`.gitverse/workflows/`): | Workflow | Триггер | Шаги | |----------|---------|------| | `python.yaml` | push / PR | Black, isort, flake8, mypy, pytest (покрытие >70%) | | `docker.yaml` | ручной | Multi-stage Docker-сборка, сохранение образа | --- ## 📝 Технологический стек | Компонент | Технология | |-----------|------------| | Runtime | Python 3.11+ (полностью async) | | Bot Framework | aiogram 3.x | | База данных | PostgreSQL 16 + pgvector | | ORM | SQLAlchemy 2.0 (async) + Alembic | | Конфигурация | Pydantic Settings v2 (YAML + ENV) | | Валидация | Pydantic v2 | | Логирование | structlog (JSON) | | HTTP Health | aiohttp | | Контейнеризация | Docker + Docker Compose | | CI/CD | GitVerse Workflows | --- ## 📜 Лицензия BSD — свободное использование, модификация и распространение в любых целях, включая коммерческие. Подробности в [LICENSE](LICENSE).

cogni-vault

AAnrullv0.1.5: настраиваемая модерация для групп, фикс дедупликации при сплите, парсинг JSON-фенсов L311 дней назадd773316Верифицирован

Описание

Страницы

Языки

Описание

Страницы

Языки

A
Anrull
v0.1.5: настраиваемая модерация для групп, фикс дедупликации при сплите, парсинг JSON-фенсов L3
11 дней назад
d773316
Верифицирован