intelliant 0.1.0a1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- intelliant-0.1.0a1/.gitignore +95 -0
- intelliant-0.1.0a1/LICENSE +7 -0
- intelliant-0.1.0a1/PKG-INFO +156 -0
- intelliant-0.1.0a1/README.md +133 -0
- intelliant-0.1.0a1/pyproject.toml +72 -0
- intelliant-0.1.0a1/src/intelliant/__init__.py +14 -0
- intelliant-0.1.0a1/src/intelliant/core_clusterer.py +541 -0
- intelliant-0.1.0a1/src/intelliant/graph_builder.py +272 -0
- intelliant-0.1.0a1/src/intelliant/pheromone_extractor.py +558 -0
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# Distribution / packaging
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
wheels/
|
|
10
|
+
*.egg-info/
|
|
11
|
+
pip-wheel-metadata/
|
|
12
|
+
|
|
13
|
+
# Installer logs
|
|
14
|
+
pip-log.txt
|
|
15
|
+
pip-delete-this-directory.txt
|
|
16
|
+
|
|
17
|
+
# Virtual environments
|
|
18
|
+
.venv/
|
|
19
|
+
venv/
|
|
20
|
+
ENV/
|
|
21
|
+
env/
|
|
22
|
+
env.bak/
|
|
23
|
+
venv.bak/
|
|
24
|
+
|
|
25
|
+
# Python dependency directories
|
|
26
|
+
.site-packages/
|
|
27
|
+
|
|
28
|
+
# PyCharm
|
|
29
|
+
.idea/
|
|
30
|
+
# Optional: if you store workspace.xml or other personal files, keep them ignored
|
|
31
|
+
# .idea/*
|
|
32
|
+
|
|
33
|
+
# VS Code
|
|
34
|
+
.vscode/
|
|
35
|
+
|
|
36
|
+
# macOS
|
|
37
|
+
.DS_Store
|
|
38
|
+
|
|
39
|
+
# Jupyter
|
|
40
|
+
.ipynb_checkpoints/
|
|
41
|
+
|
|
42
|
+
# Ruff cache
|
|
43
|
+
.ruff_cache/
|
|
44
|
+
|
|
45
|
+
# MyPy cache
|
|
46
|
+
.mypy_cache/
|
|
47
|
+
.dmypy.json
|
|
48
|
+
|
|
49
|
+
# Pytest
|
|
50
|
+
.pytest_cache/
|
|
51
|
+
|
|
52
|
+
# Coverage
|
|
53
|
+
.coverage
|
|
54
|
+
htmlcov/
|
|
55
|
+
.coverage.*
|
|
56
|
+
|
|
57
|
+
# Logs
|
|
58
|
+
*.log
|
|
59
|
+
|
|
60
|
+
# Data / datasets (ignore if you don't track data in git)
|
|
61
|
+
data/
|
|
62
|
+
dataset/
|
|
63
|
+
# If you need to keep specific files in dataset/, allow them explicitly:
|
|
64
|
+
# !dataset/README.md
|
|
65
|
+
# !dataset/small-example.csv
|
|
66
|
+
|
|
67
|
+
# Environment variables / secrets
|
|
68
|
+
.env
|
|
69
|
+
.env.*
|
|
70
|
+
|
|
71
|
+
# Build artifacts
|
|
72
|
+
*.egg
|
|
73
|
+
.eggs/
|
|
74
|
+
|
|
75
|
+
# Local sqlite/db files
|
|
76
|
+
*.sqlite3
|
|
77
|
+
*.db
|
|
78
|
+
|
|
79
|
+
# Editor swap/backup files
|
|
80
|
+
*~
|
|
81
|
+
*.swp
|
|
82
|
+
*.swo
|
|
83
|
+
|
|
84
|
+
# OS generated files
|
|
85
|
+
Thumbs.db
|
|
86
|
+
|
|
87
|
+
old_notebooks/
|
|
88
|
+
|
|
89
|
+
# Локальные заметки и агентурные директории
|
|
90
|
+
CLAUDE.md
|
|
91
|
+
TASK.md
|
|
92
|
+
code_base/
|
|
93
|
+
.claude/
|
|
94
|
+
.claw/
|
|
95
|
+
.sandbox*/
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
Copyright 2026 MIKHEYEV PAVEL
|
|
2
|
+
|
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
4
|
+
|
|
5
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
6
|
+
|
|
7
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: intelliant
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Semantic core extraction on graphs using Ant Colony Optimization
|
|
5
|
+
Project-URL: Homepage, https://github.com/yourdisenchantment/intelliant
|
|
6
|
+
Author-email: Pavel <p.idisenchantment@google.com>
|
|
7
|
+
License: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Science/Research
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
14
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
15
|
+
Requires-Python: <3.15,>=3.14
|
|
16
|
+
Requires-Dist: numba
|
|
17
|
+
Requires-Dist: numpy
|
|
18
|
+
Requires-Dist: pynndescent
|
|
19
|
+
Requires-Dist: scikit-learn
|
|
20
|
+
Requires-Dist: scipy
|
|
21
|
+
Requires-Dist: tqdm
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# Intelliant: графовый алгоритм поиска семантических ядер
|
|
25
|
+
|
|
26
|
+
[](https://opensource.org/licenses/MIT)
|
|
27
|
+
[](https://www.python.org/downloads/release/python-3140/)
|
|
28
|
+
[](https://pypi.org/project/intelliant-core/)
|
|
29
|
+
[](https://pypi.org/project/intelliant/)
|
|
30
|
+
|
|
31
|
+
**Intelliant** - специализированный алгоритм кластеризации, основанный на метаэвристике муравьиной колонии (Ant Colony Optimization, ACO).
|
|
32
|
+
|
|
33
|
+
В отличие от классических методов, алгоритм не очерчивает математические границы кластеров в гиперпространстве. Он переводит многомерные данные (например, эмбеддинги языковых моделей) в граф ближайших соседей (KNN) и использует роевой интеллект для поиска **самых плотных семантических центров (ядер)**.
|
|
34
|
+
|
|
35
|
+
Алгоритм оптимизирован через `Numba` и разреженные матрицы (Sparse CSR), что позволяет обрабатывать сотни тысяч объектов за секунды на обычных CPU, обходя ограничения памяти, свойственные индустриальным стандартам вроде HDBSCAN.
|
|
36
|
+
|
|
37
|
+
## Статус и пакеты
|
|
38
|
+
|
|
39
|
+
> **Альфа.** Пакет в стадии активной разработки (исследовательская фаза). Публичный API еще меняется между версиями. Это инструмент собственного исследования, а не готовое решение для внешних пользователей. Что сделано и что впереди - в [ROADMAP.md](ROADMAP.md); долгосрочные исследовательские идеи - в [RESEARCH_NOTES.md](RESEARCH_NOTES.md).
|
|
40
|
+
|
|
41
|
+
- **Актуальный пакет:** [`intelliant`](https://pypi.org/project/intelliant/) (текущая архитектура из трех классов).
|
|
42
|
+
- **Старый пакет (old, не поддерживается):** [`intelliant-core`](https://pypi.org/project/intelliant-core/) - одноклассовая архитектура `IntelliantCoreExtractor`. Ссылка оставлена для тех, кто пришел по старому имени; устанавливать не нужно, развитие перенесено в `intelliant`.
|
|
43
|
+
|
|
44
|
+
## Основные возможности
|
|
45
|
+
|
|
46
|
+
- **Независимость от размерности.** Работает с графом связей (cosine, euclidean), а не с сырыми координатами. Подходит и для 2D/3D, и для 384D+ эмбеддингов.
|
|
47
|
+
- **Min-Max Ant System (MMAS).** Защита от стагнации феромонов, предотвращающая коллапс графа в "черную дыру" одного хаба.
|
|
48
|
+
- **Элитные муравьи.** Ускоренное формирование ядер за счет жадного поведения выделенной группы агентов, с настраиваемой стартовой итерацией (разделение фаз exploration / exploitation).
|
|
49
|
+
- **Гравитация узлов (node density).** Опциональная эвристика: муравьи оценивают локальную плотность целевой точки, ускоряя сходимость.
|
|
50
|
+
- **Двухэтапная абсорбция шума.** Распространение меток по феромонным волнам, затем центроидный фоллбэк для изолированных точек. Доступна и как единый вызов, и по этапам (для покадровой визуализации и кэширования промежуточного состояния).
|
|
51
|
+
- **Диагностика гиганта.** Сигнализация о подозрении на склейку/раздувание кластеров по разрыву размеров (без вмешательства в данные).
|
|
52
|
+
- **Прозрачное состояние.** Все промежуточные артефакты (граф, феромонное поле, сырые ядра, метки) доступны через атрибуты для визуализации, отладки и кэширования между сессиями.
|
|
53
|
+
|
|
54
|
+
## Архитектура
|
|
55
|
+
|
|
56
|
+
Кластеризация разделена на три концептуально независимых класса, каждый в своем модуле:
|
|
57
|
+
|
|
58
|
+
| Класс | Модуль | Вход | Выход |
|
|
59
|
+
| --- | --- | --- | --- |
|
|
60
|
+
| `GraphBuilder` | `intelliant.graph_builder` | эмбеддинги `X` | граф похожестей (CSR) |
|
|
61
|
+
| `PheromoneExtractor` | `intelliant.pheromone_extractor` | граф | феромонный граф |
|
|
62
|
+
| `CoreClusterer` | `intelliant.core_clusterer` | феромонный граф + порог | метки кластеров |
|
|
63
|
+
|
|
64
|
+
Единого вызова "все в одном" нет: три части решают разные задачи (работа с данными, производство феромонов, истолкование феромонов в кластеры), и разделение сделано осознанно, чтобы каждый этап настраивался и инспектировался отдельно. Порог отсечения феромонов и извлечение эмбеддингов на текущем этапе пользователь готовит сам, вне библиотеки.
|
|
65
|
+
|
|
66
|
+
## Требования
|
|
67
|
+
|
|
68
|
+
- **Python:** `>= 3.14`
|
|
69
|
+
- **Пакетный менеджер:** `uv`
|
|
70
|
+
- **Зависимости** (ставятся автоматически): numpy, scipy, numba, scikit-learn, pynndescent, tqdm.
|
|
71
|
+
- **Аппаратное ускорение** (для генерации эмбеддингов отдельной моделью): CUDA / MPS через PyTorch - в группе зависимостей `embeddings`.
|
|
72
|
+
|
|
73
|
+
## Установка
|
|
74
|
+
|
|
75
|
+
Из PyPI (альфа):
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
pip install intelliant
|
|
79
|
+
# или явно альфа-версию:
|
|
80
|
+
pip install intelliant==0.1.0a1
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Из исходников (для разработки):
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
git clone https://github.com/yourdisenchantment/intelliant.git
|
|
87
|
+
cd intelliant
|
|
88
|
+
uv sync # только библиотека
|
|
89
|
+
uv sync --all-groups # + ноутбуки, эмбеддинги, инструменты разработки
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Группы зависимостей: `notebooks` (jupyter, визуализация, polars, umap), `embeddings` (torch, sentence-transformers, datasets), `dev` (pre-commit, ruff, pyright, scipy-stubs).
|
|
93
|
+
|
|
94
|
+
Для загрузки тестовых датасетов создайте `.env` в корне с токеном Hugging Face:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
HF_TOKEN=hf_ваша_строка_токена
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Пример использования
|
|
101
|
+
|
|
102
|
+
Пайплайн состоит из трех шагов: построение графа, прогон муравьев, извлечение кластеров. Порог отсечения феромонов задает пользователь (ниже - простой пример через перцентиль).
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
import numpy as np
|
|
106
|
+
from intelliant import GraphBuilder, PheromoneExtractor, CoreClusterer
|
|
107
|
+
|
|
108
|
+
# X - матрица эмбеддингов (N, D), подготовленная пользователем
|
|
109
|
+
|
|
110
|
+
# 1. Граф похожестей из эмбеддингов
|
|
111
|
+
graph = GraphBuilder(
|
|
112
|
+
n_neighbors=15,
|
|
113
|
+
metric="cosine",
|
|
114
|
+
mutual=True, # взаимный KNN (AND-симметризация)
|
|
115
|
+
min_connections=5, # донабор связности изолированным точкам
|
|
116
|
+
knn_method="auto", # exact для малых датасетов, approx для больших
|
|
117
|
+
random_state=42, # для воспроизводимого approx-поиска
|
|
118
|
+
).build(X)
|
|
119
|
+
|
|
120
|
+
# 2. Прогон муравьиного роя (граф -> феромонный граф)
|
|
121
|
+
aco = PheromoneExtractor(
|
|
122
|
+
n_ants=len(X), # явное число муравьев (критичный параметр)
|
|
123
|
+
n_iterations=20,
|
|
124
|
+
use_elite_ants=True,
|
|
125
|
+
elite_start_iteration=10, # элита включается с середины прогона
|
|
126
|
+
random_state=42, # сид роя (независим от сида графа)
|
|
127
|
+
)
|
|
128
|
+
aco.fit(graph)
|
|
129
|
+
pheromones = aco.pheromone_matrix_
|
|
130
|
+
|
|
131
|
+
# 3. Порог отсечения (пользователь считает сам; здесь - перцентиль)
|
|
132
|
+
threshold = np.percentile(pheromones.data, 90)
|
|
133
|
+
|
|
134
|
+
# 4. Извлечение ядер и абсорбция шума
|
|
135
|
+
clusterer = CoreClusterer(min_cluster_size=50, batch_size=200_000)
|
|
136
|
+
cores = clusterer.extract_cores(pheromones, threshold) # ядра 0..k-1, шум -1
|
|
137
|
+
labels = clusterer.absorb(pheromones, X) # достройка шума
|
|
138
|
+
|
|
139
|
+
# Промежуточное состояние доступно для диагностики и визуализации:
|
|
140
|
+
# clusterer.cores_ - сырые ядра до абсорбции
|
|
141
|
+
# clusterer.labels_pheromone_ - после феромонных волн (этап 1)
|
|
142
|
+
# clusterer.labels_ - финальные метки
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Этапы абсорбции можно вызывать раздельно (`absorb_pheromone`, затем `absorb_centroid`) - это дает три снимка состояния (сырые ядра -> после волн -> финал) и позволяет сохранять промежуточный результат между сессиями.
|
|
146
|
+
|
|
147
|
+
Каждый класс хранит результат в атрибуте с трейлинг-подчеркиванием (`graph_`, `pheromone_matrix_`, `cores_`, `labels_pheromone_`, `labels_`) по sklearn-конвенции и одновременно возвращает его из метода.
|
|
148
|
+
|
|
149
|
+
## Развитие
|
|
150
|
+
|
|
151
|
+
- **Что впереди** (текущие и ближайшие работы) - [ROADMAP.md](ROADMAP.md).
|
|
152
|
+
- **Долгосрочные исследовательские идеи** (многоуровневая иерархическая кластеризация и др.) - [RESEARCH_NOTES.md](RESEARCH_NOTES.md). Это заметки на будущее, не обязательства текущего проекта.
|
|
153
|
+
|
|
154
|
+
## Лицензия
|
|
155
|
+
|
|
156
|
+
MIT.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Intelliant: графовый алгоритм поиска семантических ядер
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
[](https://www.python.org/downloads/release/python-3140/)
|
|
5
|
+
[](https://pypi.org/project/intelliant-core/)
|
|
6
|
+
[](https://pypi.org/project/intelliant/)
|
|
7
|
+
|
|
8
|
+
**Intelliant** - специализированный алгоритм кластеризации, основанный на метаэвристике муравьиной колонии (Ant Colony Optimization, ACO).
|
|
9
|
+
|
|
10
|
+
В отличие от классических методов, алгоритм не очерчивает математические границы кластеров в гиперпространстве. Он переводит многомерные данные (например, эмбеддинги языковых моделей) в граф ближайших соседей (KNN) и использует роевой интеллект для поиска **самых плотных семантических центров (ядер)**.
|
|
11
|
+
|
|
12
|
+
Алгоритм оптимизирован через `Numba` и разреженные матрицы (Sparse CSR), что позволяет обрабатывать сотни тысяч объектов за секунды на обычных CPU, обходя ограничения памяти, свойственные индустриальным стандартам вроде HDBSCAN.
|
|
13
|
+
|
|
14
|
+
## Статус и пакеты
|
|
15
|
+
|
|
16
|
+
> **Альфа.** Пакет в стадии активной разработки (исследовательская фаза). Публичный API еще меняется между версиями. Это инструмент собственного исследования, а не готовое решение для внешних пользователей. Что сделано и что впереди - в [ROADMAP.md](ROADMAP.md); долгосрочные исследовательские идеи - в [RESEARCH_NOTES.md](RESEARCH_NOTES.md).
|
|
17
|
+
|
|
18
|
+
- **Актуальный пакет:** [`intelliant`](https://pypi.org/project/intelliant/) (текущая архитектура из трех классов).
|
|
19
|
+
- **Старый пакет (old, не поддерживается):** [`intelliant-core`](https://pypi.org/project/intelliant-core/) - одноклассовая архитектура `IntelliantCoreExtractor`. Ссылка оставлена для тех, кто пришел по старому имени; устанавливать не нужно, развитие перенесено в `intelliant`.
|
|
20
|
+
|
|
21
|
+
## Основные возможности
|
|
22
|
+
|
|
23
|
+
- **Независимость от размерности.** Работает с графом связей (cosine, euclidean), а не с сырыми координатами. Подходит и для 2D/3D, и для 384D+ эмбеддингов.
|
|
24
|
+
- **Min-Max Ant System (MMAS).** Защита от стагнации феромонов, предотвращающая коллапс графа в "черную дыру" одного хаба.
|
|
25
|
+
- **Элитные муравьи.** Ускоренное формирование ядер за счет жадного поведения выделенной группы агентов, с настраиваемой стартовой итерацией (разделение фаз exploration / exploitation).
|
|
26
|
+
- **Гравитация узлов (node density).** Опциональная эвристика: муравьи оценивают локальную плотность целевой точки, ускоряя сходимость.
|
|
27
|
+
- **Двухэтапная абсорбция шума.** Распространение меток по феромонным волнам, затем центроидный фоллбэк для изолированных точек. Доступна и как единый вызов, и по этапам (для покадровой визуализации и кэширования промежуточного состояния).
|
|
28
|
+
- **Диагностика гиганта.** Сигнализация о подозрении на склейку/раздувание кластеров по разрыву размеров (без вмешательства в данные).
|
|
29
|
+
- **Прозрачное состояние.** Все промежуточные артефакты (граф, феромонное поле, сырые ядра, метки) доступны через атрибуты для визуализации, отладки и кэширования между сессиями.
|
|
30
|
+
|
|
31
|
+
## Архитектура
|
|
32
|
+
|
|
33
|
+
Кластеризация разделена на три концептуально независимых класса, каждый в своем модуле:
|
|
34
|
+
|
|
35
|
+
| Класс | Модуль | Вход | Выход |
|
|
36
|
+
| --- | --- | --- | --- |
|
|
37
|
+
| `GraphBuilder` | `intelliant.graph_builder` | эмбеддинги `X` | граф похожестей (CSR) |
|
|
38
|
+
| `PheromoneExtractor` | `intelliant.pheromone_extractor` | граф | феромонный граф |
|
|
39
|
+
| `CoreClusterer` | `intelliant.core_clusterer` | феромонный граф + порог | метки кластеров |
|
|
40
|
+
|
|
41
|
+
Единого вызова "все в одном" нет: три части решают разные задачи (работа с данными, производство феромонов, истолкование феромонов в кластеры), и разделение сделано осознанно, чтобы каждый этап настраивался и инспектировался отдельно. Порог отсечения феромонов и извлечение эмбеддингов на текущем этапе пользователь готовит сам, вне библиотеки.
|
|
42
|
+
|
|
43
|
+
## Требования
|
|
44
|
+
|
|
45
|
+
- **Python:** `>= 3.14`
|
|
46
|
+
- **Пакетный менеджер:** `uv`
|
|
47
|
+
- **Зависимости** (ставятся автоматически): numpy, scipy, numba, scikit-learn, pynndescent, tqdm.
|
|
48
|
+
- **Аппаратное ускорение** (для генерации эмбеддингов отдельной моделью): CUDA / MPS через PyTorch - в группе зависимостей `embeddings`.
|
|
49
|
+
|
|
50
|
+
## Установка
|
|
51
|
+
|
|
52
|
+
Из PyPI (альфа):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install intelliant
|
|
56
|
+
# или явно альфа-версию:
|
|
57
|
+
pip install intelliant==0.1.0a1
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Из исходников (для разработки):
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
git clone https://github.com/yourdisenchantment/intelliant.git
|
|
64
|
+
cd intelliant
|
|
65
|
+
uv sync # только библиотека
|
|
66
|
+
uv sync --all-groups # + ноутбуки, эмбеддинги, инструменты разработки
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Группы зависимостей: `notebooks` (jupyter, визуализация, polars, umap), `embeddings` (torch, sentence-transformers, datasets), `dev` (pre-commit, ruff, pyright, scipy-stubs).
|
|
70
|
+
|
|
71
|
+
Для загрузки тестовых датасетов создайте `.env` в корне с токеном Hugging Face:
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
HF_TOKEN=hf_ваша_строка_токена
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Пример использования
|
|
78
|
+
|
|
79
|
+
Пайплайн состоит из трех шагов: построение графа, прогон муравьев, извлечение кластеров. Порог отсечения феромонов задает пользователь (ниже - простой пример через перцентиль).
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
import numpy as np
|
|
83
|
+
from intelliant import GraphBuilder, PheromoneExtractor, CoreClusterer
|
|
84
|
+
|
|
85
|
+
# X - матрица эмбеддингов (N, D), подготовленная пользователем
|
|
86
|
+
|
|
87
|
+
# 1. Граф похожестей из эмбеддингов
|
|
88
|
+
graph = GraphBuilder(
|
|
89
|
+
n_neighbors=15,
|
|
90
|
+
metric="cosine",
|
|
91
|
+
mutual=True, # взаимный KNN (AND-симметризация)
|
|
92
|
+
min_connections=5, # донабор связности изолированным точкам
|
|
93
|
+
knn_method="auto", # exact для малых датасетов, approx для больших
|
|
94
|
+
random_state=42, # для воспроизводимого approx-поиска
|
|
95
|
+
).build(X)
|
|
96
|
+
|
|
97
|
+
# 2. Прогон муравьиного роя (граф -> феромонный граф)
|
|
98
|
+
aco = PheromoneExtractor(
|
|
99
|
+
n_ants=len(X), # явное число муравьев (критичный параметр)
|
|
100
|
+
n_iterations=20,
|
|
101
|
+
use_elite_ants=True,
|
|
102
|
+
elite_start_iteration=10, # элита включается с середины прогона
|
|
103
|
+
random_state=42, # сид роя (независим от сида графа)
|
|
104
|
+
)
|
|
105
|
+
aco.fit(graph)
|
|
106
|
+
pheromones = aco.pheromone_matrix_
|
|
107
|
+
|
|
108
|
+
# 3. Порог отсечения (пользователь считает сам; здесь - перцентиль)
|
|
109
|
+
threshold = np.percentile(pheromones.data, 90)
|
|
110
|
+
|
|
111
|
+
# 4. Извлечение ядер и абсорбция шума
|
|
112
|
+
clusterer = CoreClusterer(min_cluster_size=50, batch_size=200_000)
|
|
113
|
+
cores = clusterer.extract_cores(pheromones, threshold) # ядра 0..k-1, шум -1
|
|
114
|
+
labels = clusterer.absorb(pheromones, X) # достройка шума
|
|
115
|
+
|
|
116
|
+
# Промежуточное состояние доступно для диагностики и визуализации:
|
|
117
|
+
# clusterer.cores_ - сырые ядра до абсорбции
|
|
118
|
+
# clusterer.labels_pheromone_ - после феромонных волн (этап 1)
|
|
119
|
+
# clusterer.labels_ - финальные метки
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Этапы абсорбции можно вызывать раздельно (`absorb_pheromone`, затем `absorb_centroid`) - это дает три снимка состояния (сырые ядра -> после волн -> финал) и позволяет сохранять промежуточный результат между сессиями.
|
|
123
|
+
|
|
124
|
+
Каждый класс хранит результат в атрибуте с трейлинг-подчеркиванием (`graph_`, `pheromone_matrix_`, `cores_`, `labels_pheromone_`, `labels_`) по sklearn-конвенции и одновременно возвращает его из метода.
|
|
125
|
+
|
|
126
|
+
## Развитие
|
|
127
|
+
|
|
128
|
+
- **Что впереди** (текущие и ближайшие работы) - [ROADMAP.md](ROADMAP.md).
|
|
129
|
+
- **Долгосрочные исследовательские идеи** (многоуровневая иерархическая кластеризация и др.) - [RESEARCH_NOTES.md](RESEARCH_NOTES.md). Это заметки на будущее, не обязательства текущего проекта.
|
|
130
|
+
|
|
131
|
+
## Лицензия
|
|
132
|
+
|
|
133
|
+
MIT.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "intelliant"
|
|
3
|
+
version = "0.1.0a1"
|
|
4
|
+
description = "Semantic core extraction on graphs using Ant Colony Optimization"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [{ name = "Pavel", email = "p.idisenchantment@google.com" }]
|
|
7
|
+
license = { text = "MIT" }
|
|
8
|
+
classifiers = [
|
|
9
|
+
"Development Status :: 3 - Alpha",
|
|
10
|
+
"Intended Audience :: Science/Research",
|
|
11
|
+
"License :: OSI Approved :: MIT License",
|
|
12
|
+
"Programming Language :: Python :: 3",
|
|
13
|
+
"Programming Language :: Python :: 3.14",
|
|
14
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
15
|
+
]
|
|
16
|
+
requires-python = ">=3.14,<3.15"
|
|
17
|
+
dependencies = [
|
|
18
|
+
"numpy",
|
|
19
|
+
"scipy",
|
|
20
|
+
"numba",
|
|
21
|
+
"scikit-learn",
|
|
22
|
+
"pynndescent",
|
|
23
|
+
"tqdm",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://github.com/yourdisenchantment/intelliant"
|
|
28
|
+
|
|
29
|
+
[dependency-groups]
|
|
30
|
+
notebooks = [
|
|
31
|
+
"jupyter",
|
|
32
|
+
"nbformat",
|
|
33
|
+
"matplotlib",
|
|
34
|
+
"plotly",
|
|
35
|
+
"polars",
|
|
36
|
+
"umap-learn",
|
|
37
|
+
]
|
|
38
|
+
embeddings = ["torch", "sentence-transformers", "datasets", "python-dotenv"]
|
|
39
|
+
dev = ["pre-commit", "pyright", "ruff", "scipy-stubs"]
|
|
40
|
+
|
|
41
|
+
[tool.uv.pip]
|
|
42
|
+
torch-backend = "auto"
|
|
43
|
+
|
|
44
|
+
[build-system]
|
|
45
|
+
requires = ["hatchling"]
|
|
46
|
+
build-backend = "hatchling.build"
|
|
47
|
+
|
|
48
|
+
[tool.hatch.build.targets.wheel]
|
|
49
|
+
packages = ["src/intelliant"]
|
|
50
|
+
|
|
51
|
+
[tool.hatch.build.targets.sdist]
|
|
52
|
+
include = ["src/intelliant"]
|
|
53
|
+
|
|
54
|
+
[tool.ruff]
|
|
55
|
+
line-length = 120
|
|
56
|
+
target-version = "py314"
|
|
57
|
+
|
|
58
|
+
[tool.ruff.lint]
|
|
59
|
+
select = ["E", "F", "I", "W", "UP"]
|
|
60
|
+
ignore = []
|
|
61
|
+
|
|
62
|
+
[tool.ruff.format]
|
|
63
|
+
quote-style = "double"
|
|
64
|
+
indent-style = "space"
|
|
65
|
+
docstring-code-format = true
|
|
66
|
+
|
|
67
|
+
[tool.pyright]
|
|
68
|
+
include = ["src/intelliant"]
|
|
69
|
+
pythonVersion = "3.14"
|
|
70
|
+
typeCheckingMode = "standard"
|
|
71
|
+
venvPath = "."
|
|
72
|
+
venv = ".venv"
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# src/intelliant/__init__.py
|
|
2
|
+
|
|
3
|
+
"""Intelliant: выделение семантических ядер на графах через ACO.
|
|
4
|
+
|
|
5
|
+
Публичный API: GraphBuilder (граф сходства из эмбеддингов), PheromoneExtractor
|
|
6
|
+
(феромонное поле алгоритмом ACO), CoreClusterer (извлечение ядер и абсорбция).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from .core_clusterer import CoreClusterer
|
|
10
|
+
from .graph_builder import GraphBuilder
|
|
11
|
+
from .pheromone_extractor import PheromoneExtractor
|
|
12
|
+
|
|
13
|
+
__version__ = "0.1.0a1"
|
|
14
|
+
__all__ = ["CoreClusterer", "GraphBuilder", "PheromoneExtractor"]
|