Metadata-Version: 2.4
Name: intelliant
Version: 0.1.0a1
Summary: Semantic core extraction on graphs using Ant Colony Optimization
Project-URL: Homepage, https://github.com/yourdisenchantment/intelliant
Author-email: Pavel <p.idisenchantment@google.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.14
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pynndescent
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: tqdm
Description-Content-Type: text/markdown

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/downloads/release/python-3140/)
[![intelliant-core (old)](https://img.shields.io/badge/intelliant--core-old%20%2F%20deprecated-lightgrey.svg)](https://pypi.org/project/intelliant-core/)
[![intelliant](https://img.shields.io/badge/intelliant-0.1.0a1%20alpha-orange.svg)](https://pypi.org/project/intelliant/)

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

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

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

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

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

- **Актуальный пакет:** [`intelliant`](https://pypi.org/project/intelliant/) (текущая архитектура из трех классов).
- **Старый пакет (old, не поддерживается):** [`intelliant-core`](https://pypi.org/project/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 (альфа):

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

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

```bash
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:

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

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

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

```python
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](ROADMAP.md).
- **Долгосрочные исследовательские идеи** (многоуровневая иерархическая кластеризация и др.) - [RESEARCH_NOTES.md](RESEARCH_NOTES.md). Это заметки на будущее, не обязательства текущего проекта.

## Лицензия

MIT.
