intelliant 0.1.0a1

Semantic core extraction on graphs using Ant Colony Optimization

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

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

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

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

Статус и пакеты

Альфа. Пакет в стадии активной разработки (исследовательская фаза). Публичный API еще меняется между версиями. Это инструмент собственного исследования, а не готовое решение для внешних пользователей. Что сделано и что впереди - в ROADMAP.md; долгосрочные исследовательские идеи - в RESEARCH_NOTES.md.

• Актуальный пакет: intelliant (текущая архитектура из трех классов).
• Старый пакет (old, не поддерживается): intelliant-core - одноклассовая архитектура IntelliantCoreExtractor. Ссылка оставлена для тех, кто пришел по старому имени; устанавливать не нужно, развитие перенесено в intelliant.

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

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

Архитектура

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

Класс	Модуль	Вход	Выход
GraphBuilder	intelliant.graph_builder	эмбеддинги X	граф похожестей (CSR)
PheromoneExtractor	intelliant.pheromone_extractor	граф	феромонный граф
CoreClusterer	intelliant.core_clusterer	феромонный граф + порог	метки кластеров

Единого вызова "все в одном" нет: три части решают разные задачи (работа с данными, производство феромонов, истолкование феромонов в кластеры), и разделение сделано осознанно, чтобы каждый этап настраивался и инспектировался отдельно. Порог отсечения феромонов и извлечение эмбеддингов на текущем этапе пользователь готовит сам, вне библиотеки.

Требования

• Python: >= 3.14
• Пакетный менеджер: uv
• Зависимости (ставятся автоматически): numpy, scipy, numba, scikit-learn, pynndescent, tqdm.
• Аппаратное ускорение (для генерации эмбеддингов отдельной моделью): CUDA / MPS через PyTorch - в группе зависимостей embeddings.

Установка

Из PyPI (альфа):

pip install intelliant
# или явно альфа-версию:
pip install intelliant==0.1.0a1

Из исходников (для разработки):

git clone https://github.com/yourdisenchantment/intelliant.git
cd intelliant
uv sync                       # только библиотека
uv sync --all-groups          # + ноутбуки, эмбеддинги, инструменты разработки

Группы зависимостей: notebooks (jupyter, визуализация, polars, umap), embeddings (torch, sentence-transformers, datasets), dev (pre-commit, ruff, pyright, scipy-stubs).

Для загрузки тестовых датасетов создайте .env в корне с токеном Hugging Face:

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

Пример использования

Пайплайн состоит из трех шагов: построение графа, прогон муравьев, извлечение кластеров. Порог отсечения феромонов задает пользователь (ниже - простой пример через перцентиль).

import numpy as np
from intelliant import GraphBuilder, PheromoneExtractor, CoreClusterer

# X - матрица эмбеддингов (N, D), подготовленная пользователем

# 1. Граф похожестей из эмбеддингов
graph = GraphBuilder(
    n_neighbors=15,
    metric="cosine",
    mutual=True,         # взаимный KNN (AND-симметризация)
    min_connections=5,   # донабор связности изолированным точкам
    knn_method="auto",   # exact для малых датасетов, approx для больших
    random_state=42,     # для воспроизводимого approx-поиска
).build(X)

# 2. Прогон муравьиного роя (граф -> феромонный граф)
aco = PheromoneExtractor(
    n_ants=len(X),              # явное число муравьев (критичный параметр)
    n_iterations=20,
    use_elite_ants=True,
    elite_start_iteration=10,   # элита включается с середины прогона
    random_state=42,            # сид роя (независим от сида графа)
)
aco.fit(graph)
pheromones = aco.pheromone_matrix_

# 3. Порог отсечения (пользователь считает сам; здесь - перцентиль)
threshold = np.percentile(pheromones.data, 90)

# 4. Извлечение ядер и абсорбция шума
clusterer = CoreClusterer(min_cluster_size=50, batch_size=200_000)
cores = clusterer.extract_cores(pheromones, threshold)   # ядра 0..k-1, шум -1
labels = clusterer.absorb(pheromones, X)                 # достройка шума

# Промежуточное состояние доступно для диагностики и визуализации:
#   clusterer.cores_             - сырые ядра до абсорбции
#   clusterer.labels_pheromone_  - после феромонных волн (этап 1)
#   clusterer.labels_            - финальные метки

Этапы абсорбции можно вызывать раздельно (absorb_pheromone, затем absorb_centroid) - это дает три снимка состояния (сырые ядра -> после волн -> финал) и позволяет сохранять промежуточный результат между сессиями.

Каждый класс хранит результат в атрибуте с трейлинг-подчеркиванием (graph_, pheromone_matrix_, cores_, labels_pheromone_, labels_) по sklearn-конвенции и одновременно возвращает его из метода.

Развитие

• Что впереди (текущие и ближайшие работы) - ROADMAP.md.
• Долгосрочные исследовательские идеи (многоуровневая иерархическая кластеризация и др.) - RESEARCH_NOTES.md. Это заметки на будущее, не обязательства текущего проекта.

Лицензия

MIT.