mindbank-poc 0.1.1

Mindbank PoC: Data ingestion and processing platform

Mindbank PoC

Proof of Concept для платформы Mindbank - системы сбора и обработки данных из различных источников.

Архитектура

Система построена по модульному принципу и включает следующие компоненты:

1. Core - основные компоненты системы:

   • Buffer - буферизация и агрегация входящих данных
   • Storage - хранение данных
   • Queue - асинхронная обработка агрегатов
   • Normalizer - преобразование агрегатов в нормализованные единицы
   • Knowledge Store - хранение нормализованных единиц
   • Security - управление интеграционными ключами и токенами доступа

2. API - REST API для приема данных:

   • Ingest API - прием сырых данных и агрегатов
   • Connector API - управление жизненным циклом коннекторов
   • Admin API - административные функции с защитой
   • Query API (планируется) - доступ к сохраненным данным

3. Connectors - коннекторы для различных источников данных:

   • Debug - генерация тестовых данных
   • FileSystem - чтение файлов из файловой системы
   • Telegram (планируется) - сбор данных из Telegram

Поток данных

Коннекторы → Регистрация → Handshake → RawEntry → [буферизация] → Aggregate → [очередь] → 
Normalizer → [провайдеры нормализации] → NormalizedUnit → Knowledge Store

Система безопасности

Система использует двухуровневый подход к безопасности:

1. Интеграционные ключи - долгоживущие токены для идентификации типов коннекторов

   • Управляются администратором через защищенные эндпоинты
   • Ограничены типами поддерживаемых коннекторов
   • Используются только для регистрации коннекторов

2. Токены доступа - короткоживущие токены для авторизации коннекторов

   • Генерируются при регистрации коннектора
   • Обновляются при изменении конфигурации
   • Используются для отправки данных и handshake

3. Административный доступ - базовая аутентификация для административных эндпоинтов

   • Защита эндпоинтов управления интеграционными ключами
   • Защита эндпоинтов управления коннекторами

Модульная независимость

Все компоненты системы спроектированы как независимые модули с минимальными перекрестными зависимостями:

1. Core - базовые функции, используемые другими модулями
2. API - зависит только от Core
3. Connectors - полностью независимые модули, зависящие только от HTTP библиотек для взаимодействия с API

Каждый модуль имеет свой набор зависимостей, которые устанавливаются только при необходимости использования конкретного модуля, что позволяет:

• Уменьшить объем зависимостей
• Изолировать проблемы между модулями
• Развивать компоненты независимо друг от друга

Нормализация данных

Система использует провайдерную архитектуру для нормализации данных с возможностью fallback:

1. Transcript Provider - преобразование аудио/видео в текст

   • OpenAI Whisper API - основной провайдер для транскрипции
   • Fallback Provider - локальный провайдер для работы в offline-режиме

2. Caption Provider - генерация описаний изображений

   • OpenAI GPT-4V - основной провайдер для описания изображений
   • Fallback Provider - локальный провайдер для работы в offline-режиме

3. Embed Provider - векторизация текста

   • OpenAI Embedding API - основной провайдер для векторизации
   • Fallback Provider - локальный провайдер для работы в offline-режиме

4. Classifier Provider - классификация контента

   • OpenAI GPT - основной провайдер для классификации
   • Fallback Provider - локальный провайдер для работы в offline-режиме

Нормализатор поддерживает два режима работы:

• Online - использование внешних API для обработки данных (OpenAI)
• Offline - использование локальных fallback-провайдеров

Конфигурация нормализатора управляется через переменные окружения в .env файле:

# Настройки нормализатора
NORMALIZER_OFFLINE_MODE=false
NORMALIZER_TRANSCRIPT_PROVIDER=openai
NORMALIZER_CAPTION_PROVIDER=openai
NORMALIZER_EMBED_PROVIDER=openai
NORMALIZER_CLASSIFIER_PROVIDER=openai

# Настройки OpenAI API
OPENAI_API_KEY=your-api-key-here
OPENAI_ORGANIZATION_ID=your-org-id-here

# Модели OpenAI
OPENAI_WHISPER_MODEL=whisper-1
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002
OPENAI_CAPTION_MODEL=gpt-4o-mini
OPENAI_CLASSIFIER_MODEL=gpt-4o-mini

# Флаги включения провайдеров 
NORMALIZER_ENABLE_TRANSCRIPT=true
NORMALIZER_ENABLE_CAPTION=true
NORMALIZER_ENABLE_EMBED=true
NORMALIZER_ENABLE_CLASSIFIER=true

Спецификация коннекторов

Подробная спецификация для разработки коннекторов доступна в файле CONNECTOR_SPEC.md.

Основные принципы коннекторов:

• Единый интерфейс взаимодействия с Ingest API
• Независимость от ядра системы
• Собственные зависимости и конфигурация
• Единая модель данных для всех коннекторов
• Безопасный процесс регистрации и аутентификации
• Жизненный цикл с управляемыми состояниями (stage, enabled), включая поддержку сложного многошагового онбоардинга через FSM.

Жизненный цикл коннектора

1. Регистрация - коннектор регистрируется в системе, используя интеграционный ключ. При регистрации он передает свою config_schema (схему финальной конфигурации), опционально config (начальную конфигурацию), и setup_details (если требуется сложная первоначальная настройка через собственный UI/CLI коннектора).
2. Handshake / FSM Sync (Онбоардинг) -
   • Простой онбоардинг/Конфигурация: Если setup_details не предоставлены, коннектор может сразу перейти в состояние READY (если config валидна и skip_periodic_handshake: true, или config валидна и skip_periodic_handshake: false), либо в CONFIGURATION (если config невалидна/отсутствует, а config_schema требует поля). В состоянии CONFIGURATION администратор настраивает коннектор через Mindbank API.
   • Сложный онбоардинг (FSM): Если при регистрации были предоставлены setup_details.setup_url (и skip_periodic_handshake: false), коннектор переходит в состояние SETUP_REQUIRED. Администратор использует setup_url для настройки коннектора через его собственный интерфейс. После завершения настройки в своем UI, коннектор отправляет полную итоговую конфигурацию в Mindbank API (POST /connectors/{id}/config). Для более сложных, интерактивных сценариев онбоардинга, где требуется несколько шагов обмена данными между UI Mindbank и логикой коннектора, используется FSM-протокол: UI Mindbank вызывает эндпоинты /onboard/..., а коннектор синхронизируется с FSM Ingest API через эндпоинты /fsm/... (см. CONNECTOR_SPEC.md для деталей).
3. Handshake (Операционный режим) - После онбоардинга и валидной конфигурации (коннектор в stage: READY), коннектор периодически выполняет GET /connectors/{id}/handshake для синхронизации состояния, получения обновленной конфигурации или нового токена доступа (если не используется skip_periodic_handshake: true).
4. Отправка данных - передача данных (RawEntry) на эндпоинт POST /connectors/{id}/data с использованием актуального access_token.
5. Управление - обновление конфигурации (PATCH /connectors/{id} администратором), включение/отключение (POST /connectors/{id}/toggle администратором), сброс конфигурации или полный сброс (POST /connectors/{id}/reset-config, POST /connectors/{id}/reset-setup коннектором).
6. (Опционально) Уведомление об изменении динамических опций - Коннектор может уведомить Ingest API (POST /connectors/{id}/fsm/notify_dynamic_config_update) о том, что его динамические опции конфигурации изменились, чтобы API запросил их обновление через FSM-протокол.

Документация

Техническое задание и ход реализации

• HUB_INTEGRATION_TZ.md - Техническое задание по интеграции Hub и доработке платформы
• IMPLEMENTATION_LOG.md - Журнал реализации задач из технического задания
• MindBank_Hub_Concept.md - Концепция Hub-интерфейса
• MindBank-as-global-info-core.md - Концепция MindBank как глобального информационного ядра

Спецификация коннекторов

Подробная спецификация для разработки коннекторов доступна в файле CONNECTOR_SPEC.md.

Running

API

Запуск API:

# Установка зависимостей
uv pip install -e '.[api]'

# Запуск API (вариант 1)
python -m uvicorn mindbank_poc.api.main:app --reload --port 8000

# Запуск API (вариант 2)
uv run uvicorn mindbank_poc.api.main:app --reload --port 8000

# Запуск API с помощью команды run-core (после установки пакета)
run-core --host localhost --port 8000 --reload

Обратите внимание: команда uv run python uvicorn mindbank_poc.api.main:app --reload --port 8000 некорректна, так как uvicorn - это отдельная команда, а не аргумент для python.

Защищенные API

Запуск API с защитой административных эндпоинтов:

# Конфигурация .env
ADMIN_USERNAME=admin
ADMIN_PASSWORD_HASH=bcrypt_hash_of_your_password

# Запуск API
uvicorn mindbank_poc.api.main:app --reload --port 8000

Connectors

Debug Connector

# Установка зависимостей
uv pip install -e '.[connectors-debug]'

# Запуск Debug коннектора
python -m mindbank_poc.connectors.debug.client --batch-size 5 --total 20

FileSystem Connector

# Установка зависимостей
uv pip install -e '.[connectors-filesystem]'

# Запуск FileSystem коннектора
python -m mindbank_poc.connectors.filesystem.client ./data/input --extensions .txt,.md,.json

Telegram Connector

# Установка зависимостей
uv pip install -e '.[connectors-telegram]'

# Запуск Telegram коннектора (вариант 1)
python -m mindbank_poc.connectors.telegram.main --api-url http://localhost:8000 --integration-key your-integration-key

# Запуск Telegram коннектора с помощью команды run-tg-connector (после установки пакета)
run-tg-connector --api-url http://localhost:8000 --integration-key your-integration-key

MindBank Client

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

# Установка зависимостей
uv pip install -e '.[all]'

# Запуск только API-сервера (Core)
mind-client core --host 0.0.0.0 --port 8000 --reload

# Запуск только Telegram-коннектора
mind-client telegram --api-url http://localhost:8000 --integration-key your-integration-key

# Запуск и API-сервера, и Telegram-коннектора одновременно
mind-client all --host 0.0.0.0 --port 8000 --integration-key your-integration-key

Standalone CLI команды

# Установка пакета
pip install mindbank-poc

# Запуск только ядра системы (Core)
run-core --host 0.0.0.0 --port 8000 --offline-mode

# Запуск только Telegram коннектора
run-tg-connector --api-url http://localhost:8000 --integration-key your-integration-key

Normalizer

Тестирование нормализатора

# Установка зависимостей
uv pip install -e '.[cli]'

# Запуск нормализатора на существующем агрегате
mindbank-normalizer --jsonl-file data/ingest_jsonl/aggregates.jsonl

# Запуск в offline режиме (использовать fallback провайдеры)
mindbank-normalizer --jsonl-file data/ingest_jsonl/aggregates.jsonl --offline

# Принудительное использование OpenAI провайдеров
mindbank-normalizer --jsonl-file data/ingest_jsonl/aggregates.jsonl --openai

# Сохранение результата в файл
mindbank-normalizer --jsonl-file data/ingest_jsonl/aggregates.jsonl --output data/knowledge_store/test_unit.jsonl

Конфигурация нормализатора в .env

# Настройки OpenAI API
OPENAI_API_KEY=your-api-key-here
OPENAI_ORGANIZATION_ID=your-org-id-here

# Модели OpenAI
OPENAI_WHISPER_MODEL=whisper-1
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002
OPENAI_CAPTION_MODEL=gpt-4o-mini
OPENAI_CLASSIFIER_MODEL=gpt-4o-mini

# Настройки нормализатора
NORMALIZER_OFFLINE_MODE=false
NORMALIZER_TRANSCRIPT_PROVIDER=openai
NORMALIZER_CAPTION_PROVIDER=openai
NORMALIZER_EMBED_PROVIDER=openai
NORMALIZER_CLASSIFIER_PROVIDER=openai

# Флаги включения провайдеров 
NORMALIZER_ENABLE_TRANSCRIPT=true
NORMALIZER_ENABLE_CAPTION=true
NORMALIZER_ENABLE_EMBED=true
NORMALIZER_ENABLE_CLASSIFIER=true

Development

Installation

# Клонирование репозитория
git clone [e-mail]:ml/mindbank-poc.git
cd mindbank-poc

# Установка всех зависимостей для разработки
uv pip install -e '.[all]'

Testing

# Запуск всех тестов
pytest

# Запуск тестов для конкретного модуля
pytest tests/core
pytest tests/api

Integration Keys for Connectors

MindBank uses integration keys as a secure way to authenticate connectors with the Core API. These keys are used to authorize connector instances to interact with MindBank's knowledge graph and processing pipelines.

How Integration Keys Work

1. Generation: Integration keys are generated by the Core API when a connector is registered or through dedicated endpoints.
2. Usage: The integration key serves as an authentication token for the connector, ensuring secure communication with Core API.
3. Revocation: Keys can be revoked if compromised or no longer needed, and new keys can be generated.

Integration Key Management

Integration keys can be managed in various ways:

• Via Hub UI: The ConnectorSettingsDialog allows viewing, generating, and revoking integration keys for installed connectors.
• Programmatically: The IntegrationKeyService provides methods to create, retrieve, and revoke integration keys.
• API Endpoints: Core API exposes endpoints for integration key management:
  • /integration-keys - For general key management (GET/POST)
  • /integration-keys/{key_id} - For specific key operations (GET)
  • /integration-keys/{key_id}/revoke - For revoking a specific key (POST)
  • /connectors/{connector_id}/integration-key - For connector-specific key generation (POST)
  • /connectors/{connector_id}/revoke-key - For revoking connector-specific keys (POST)

Manual Connector Installation

For connectors that run outside of the Hub (such as on remote servers), you can use the manual installation method:

1. Select a connector in the Hub's "Available Connectors" section
2. Choose "Manual" as the installation method
3. The Hub will generate an integration key automatically
4. Use this key with the Core API URL in your connector's environment configuration:

   CORE_API_URL=http://your-core-instance:8000
   CORE_TOKEN=your-integration-key
   

5. The connector will authenticate with Core API using this integration key

Security Considerations

• Integration keys should be treated as sensitive credentials
• Use secure methods to transfer and store keys
• Revoke keys when they are no longer needed
• Configuration files containing keys should have proper access controls