intelliant-core 0.1.1

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 для загрузки тестовых датасетов.

---

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

Установка через PyPI (Для использования библиотеки)

Пакет официально опубликован на PyPI. Вы можете установить ядро алгоритма с помощью pip или uv:

pip install intelliant-core
# или
uv add intelliant-core

Установка для разработки (Сборка из исходников и тесты)

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

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 для линтинга).

---

Пример использования (Quick Start)

Алгоритм принимает на вход любую разреженную матрицу графа (SciPy CSR Matrix). Ниже приведен базовый пайплайн работы:

import numpy as np
from intelliant_core import IntelliantCoreExtractor

# Вспомогательные функции (доступны в папке utils/ репозитория)
from utils.utils import build_knn_graph, get_threshold, absorb_noise

# 1. Построение разреженного KNN-графа из эмбеддингов (N, D)
knn_graph = build_knn_graph(X_embeddings, n_neighbors=15, metric="cosine")

# 2. Инициализация и запуск муравьиного роя
aco = IntelliantCoreExtractor(
    n_ants=1000,
    n_iterations=20,
    use_elite_ants=True,
    verbose=True
)
aco.fit(knn_graph, initial_pheromone=1.0)

# 3. Динамическое отсечение слабых связей (автоматический порог Оцу)
pheros = aco.pheromone_matrix.data
_, cutoff_val = get_threshold(pheros, method="otsu")
raw_labels, n_clusters = aco.get_labels(threshold_value=cutoff_val)

# 4. Поглощение пограничного шума (опционально)
final_labels = absorb_noise(X_embeddings, raw_labels, min_cluster_size=50)

---

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

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

---

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

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

• Разработка адаптивного (динамического) cutoff на основе анализа графика распределения феромонов (отказ от жестко заданного процентиля).
• Миграция на архитектуру src-layout, настройка сборки пакета через hatchling/uv и успешная публикация библиотеки на PyPI.
• Внедрение системы автокалибровки гиперпараметров (число муравьев, длина пути, испарение) на основе метрик связности входящего KNN-графа.
• Проведение экспериментов на эмбеддингах различной размерности: сравнение легковесных моделей с тяжеловесными (например, использование google/embeddinggemma-300m для генерации векторов разной размерности) для проверки аппаратной устойчивости алгоритма.