Metadata-Version: 2.4
Name: intelliant-core
Version: 0.1.0
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: Графовый алгоритм поиска семантических ядер

**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. **Клонируйте репозиторий:**

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

---

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

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

---

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

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

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