Metadata-Version: 2.4
Name: intelliant-core
Version: 0.1.1
Summary: Semantic core extraction on graphs using Ant Colony Optimization
Project-URL: Homepage, https://github.com/yourdisenchantment/intelliant-core
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: scipy
Requires-Dist: tqdm
Provides-Extra: lint
Requires-Dist: ruff; extra == 'lint'
Description-Content-Type: text/markdown

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

[![PyPI version](https://badge.fury.io/py/intelliant-core.svg)](https://pypi.org/project/intelliant-core/)
[![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/downloads/release/python-3140/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

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

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

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

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

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

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

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

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

   ```bash
   uv sync --all-groups --all-extras
   ```

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

---

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

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

```python
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)._

---

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

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

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