intelliant-core 0.1.0

Semantic core extraction on graphs using Ant Colony Optimization

Intelliant Core: Графовый алгоритм поиска семантических ядер

Intelliant Core - это специализированный алгоритм машинного обучения, основанный на метаэвристике муравьиной колонии (Ant Colony Optimization, ACO).

В отличие от классических методов, алгоритм не пытается очертить математические границы кластеров в гиперпространстве. Он переводит многомерные данные (например, эмбеддинги языковых моделей) в формат графа ближайших соседей (KNN) и использует роевой интеллект для поиска самых плотных семантических центров (ядер).

Алгоритм оптимизирован через Numba и разреженные матрицы (Sparse CSR), что позволяет ему обрабатывать сотни тысяч объектов за несколько секунд на обычных CPU, обходя ограничения памяти (OOM), свойственные индустриальным стандартам вроде HDBSCAN.

Основные возможности и особенности

• Независимость от размерности: Работает с графом связей (cosine, euclidean), а не с сырыми координатами. Отлично подходит как для 2D/3D пространств, так и для 384D+ эмбеддингов.
• Min-Max Ant System (MMAS): Защита от стагнации феромонов, предотвращающая коллапс графа в "черную дыру" одного хаба.
• Elitist Ants (Элитные муравьи): Ускоренное формирование ядер за счет жадного поведения выделенной группы агентов.
• Node Density (Гравитация узлов): Опциональная эвристика, позволяющая муравьям оценивать локальную плотность целевой точки, ускоряя сходимость алгоритма в 2 раза.
• Noise Absorption: Встроенный модуль абсорбции для перераспределения пограничных точек (шума) по найденным ядрам через взвешенный KNN.

---

Требования и технологии

Для обеспечения максимальной производительности и воспроизводимости проект опирается на современный стек Python:

• Python: >= 3.14
• Пакетный менеджер: uv (обеспечивает сверхбыстрое разрешение зависимостей)
• Аппаратное ускорение: Поддержка CUDA (NVIDIA) и MPS (Apple Silicon) для генерации эмбеддингов через PyTorch.
• Необходима настройка токена Hugging Face для загрузки тестовых датасетов.

---

Установка и запуск

1. Клонируйте репозиторий:

   git clone https://github.com/yourdisenchantment/intelliant-core.git
   cd intelliant-core
   

2. Создайте файл .env в корне проекта: Добавьте в него ваш токен от Hugging Face для загрузки датасетов (например, AG_NEWS):

   HF_API_TOKEN=hf_ваша_строка_токена
   

3. Установите все зависимости проекта: Используйте менеджер uv для установки всех зависимостей (базовые, ML, Dev + Optional):

   uv sync --all-groups --all-extras
   

   Примечание: --all-groups устанавливает базовые зависимости, ML и dev-пакеты (включая pre-commit), а --all-extras добавляет опциональные пакеты (включая ruff для линтинга).

---

Структура тестов

(Секция в процессе заполнения. Вскоре здесь появятся описания тестовых блокнотов, демонстрирующих работу алгоритма на синтетических данных и сравнение с HDBSCAN).

---

План развития

Проект находится в стадии активного полишинга. Запланированные нововведения:

• Разработка адаптивного (динамического) cutoff на основе анализа графика распределения феромонов (отказ от жестко заданного процентиля).
• Очистка кодовой базы, упаковка класса IntelliantCoreExtractor и вспомогательных утилит в полноценную open-source Python-библиотеку (с последующей публикацией на PyPI).
• Внедрение системы автокалибровки гиперпараметров (число муравьев, длина пути, испарение) на основе метрик связности входящего KNN-графа.
• Проведение экспериментов на эмбеддингах различной размерности: сравнение легковесных моделей с тяжеловесными (например, использование google/embeddinggemma-300m для генерации векторов разной размерности) для проверки аппаратной устойчивости алгоритма.