Metadata-Version: 2.4
Name: sloy_AI
Version: 0.2.0
Summary: Memory-aware block training for small language models on MLX
Author: salyukov.gleb033
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/salyukov.gleb033/sloy_ai
Project-URL: Documentation, https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/README.md
Project-URL: Repository, https://gitlab.com/salyukov.gleb033/sloy_ai.git
Project-URL: Issues, https://gitlab.com/salyukov.gleb033/sloy_ai/-/issues
Project-URL: Changelog, https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/CHANGELOG.md
Keywords: mlx,language-model,block-training,checkpoint,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: mlx<0.33,>=0.32.3
Requires-Dist: numpy<3,>=2
Requires-Dist: textual<9,>=8.2
Requires-Dist: PyYAML<7,>=6
Requires-Dist: psutil<8,>=7
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=1; extra == "test"
Provides-Extra: docs
Requires-Dist: matplotlib<4,>=3.9; extra == "docs"
Provides-Extra: release
Requires-Dist: build<2,>=1.2; extra == "release"
Requires-Dist: twine<8,>=7; extra == "release"
Dynamic: license-file

# Слой_AI

### Python-библиотека для обучения небольших языковых моделей на MLX

Обучение по блокам. Контроль памяти. Python API и команда `sloy`.

[![PyPI](https://img.shields.io/pypi/v/sloy-ai?color=18a999&cacheSeconds=300)](https://pypi.org/project/sloy-ai/)
[![Python](https://img.shields.io/badge/Python-3.11%2B-3876ab)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-18a999)](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/LICENSE)
[![MLX](https://img.shields.io/badge/compute-MLX-151e2b)](https://ml-explore.github.io/mlx/)

**Библиотека уже доступна на [PyPI: sloy-ai](https://pypi.org/project/sloy-ai/).**

```bash
python -m pip install sloy-ai
```

```python
from sloy_AI import train
from sloy_AI.config import Config
```

**Обучение с нуля одной командой (0.2.0):**

```bash
sloy train --model auto --data dialogs.jsonl --memory-budget-gb 4 --run runs/first
sloy help all
```

TXT/JSONL → проверка и разделение данных → подбор архитектуры и микробатча → обучение →
полные веса в `runs/first/model/` и отчёт `report.md`. В панели **H / F1** открывает шпаргалки.
[Руководство по новому сценарию](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/from-scratch.md).

Python 3.11+ · macOS на Apple Silicon · MLX / Metal.
[Пример обучения из Python](#python-api) · [Установка и первый запуск](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/getting-started.md)

**Слой_AI** — Python-библиотека для обучения небольших causal Transformer на MLX.
Она умеет обновлять отдельные группы слоёв, кэшировать неизменный префикс и подбирать
микробатч по короткому замеру памяти. Обучением можно управлять из терминала или Python,
останавливать его на безопасной границе и продолжать из сохранённого состояния.

> **Опубликовано: [0.2.0 на PyPI](https://pypi.org/project/sloy-AI/0.2.0/) · Alpha.** Сейчас поддерживается собственная модель float32 с байтовой
> токенизацией. Это инструмент для небольших экспериментов, а не обещание обучать
> произвольные большие модели на любом компьютере.

[Быстрый старт](#быстрый-старт) · [Консоль](#консоль-которая-показывает-работу) ·
[Как это работает](#как-это-работает) · [Продолжение](#сохранить-сейчас-продолжить-позже) ·
[Python API](#python-api) · [Результаты](#что-показывают-измерения) ·
[Документация](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/README.md)

![Терминальная панель Слой_AI](https://gitlab.com/salyukov.gleb033/sloy_ai/-/raw/main/docs/assets/dashboard.png)

*Панель на метриках реального короткого запуска. Для публикации скрыты только локальные пути.*

## Документация

| Начать | Использовать | Разрабатывать |
|---|---|---|
| [Первый запуск до генерации](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/getting-started.md) | [Все команды CLI](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/cli.md) | [Участие в проекте](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/CONTRIBUTING.md) |
| [Требования и ошибки установки](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/troubleshooting.md) | [Python API](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/python-api.md) | [Архитектура](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/architecture.md) |
| [Термины и единицы](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/glossary.md) | [Конфигурация](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/configuration.md) | [Выпуск на PyPI](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/releasing.md) |

## Что внутри

| Возможность | Поведение |
|---|---|
| Запуск с нуля одной командой | TXT/JSONL, архитектуры tiny/small/medium, автоматический экспорт и отчёт |
| Шпаргалки внутри консоли | `sloy help`, темы справки, H/F1 во время обучения |
| Три режима обучения | Все веса, группы по очереди, экспериментальный адаптивный выбор |
| Корректный backward | Замороженный суффикс пропускает градиент к обучаемой группе |
| Кэш префикса | Дисковый float32-кэш с проверкой весов, данных, токенизации и контекста |
| Подбор микробатча | Изолированные пробные процессы, резерв памяти, неизменный контекст |
| Продолжение | Веса, Adam, RNG, данные, scheduler, метрики и часы в одном checkpoint |
| Консоль | Textual, горячие клавиши, графики, логи; plain-режим для скриптов |
| Экспорт | Модель отдельно от полного состояния обучения; latest или best |

## Быстрый старт

### 1. Установите пакет

Нужны **Python 3.11+**, macOS на Apple Silicon и совместимая версия MLX с Metal.
Поддержка конкретной версии macOS определяется доступностью wheel MLX. Остальные
платформы не входят в проверенный сценарий этого выпуска.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'sloy-ai==0.2.0'
```

Название дистрибутива на PyPI нормализуется до `sloy-ai`, Python-import — `sloy_AI`,
команда терминала — `sloy`. Для установки исходников:

```bash
git clone https://gitlab.com/salyukov.gleb033/sloy_ai.git
cd sloy_ai
python -m pip install -e '.[test]'
```

### 2. Создайте пример

```bash
sloy init --directory my-first-model
```

Команда создаст `tiny.yaml` и небольшой `corpus.txt` из ресурсов пакета. Модели и
датасеты не скачиваются. Существующая папка не перезаписывается.

### 3. Запустите обучение

```bash
sloy train --config my-first-model/tiny.yaml --memory-budget-gb 4
```

Сначала выполняется короткий пробник. Затем открывается панель. Каждый запуск получает
свою папку в `runs/`. В комплектном примере план составляет **34 шага за 2 эпохи**:
`max_steps: 40` — верхняя граница, а не обещание выполнить лишние шаги.

Хотите выбрать путь сами или перенаправить вывод:

```bash
sloy train --config my-first-model/tiny.yaml --run runs/first --plain
```

После этого продолжение — `sloy resume --run runs/first`, экспорт —
`sloy export --run runs/first --output exports/first`.

## Консоль, которая показывает работу

Панель выводит модель, устройство, параметры, общий план, эпоху, optimizer step,
скорость, train loss, последний validation loss и схему активных блоков.
Отдельные индикаторы показывают данные, кэш, обучение, проверку и сохранение.

```text
╱╱ СЛОЙ_AI    Обучение
sloy-tiny  •  MLX gpu  •  sequential
context 32  |  batch 8  |  microbatch 8

План optimizer steps  ━━━━━━━━━━──────────  50.0%
Эпоха 1/2  •  шаг 17/34

○ Emb  →  ○ B1  →  ● B2  →  ○ B3  →  ○ Head
                  обучается

[P] Пауза   [R] Продолжить   [S] Сохранить   [Q] Сохранить и выйти
```

*Схематический фрагмент интерфейса; фактические значения зависят от запуска.*

| Действие | Клавиша | Когда выполняется |
|---|---|---|
| Пауза + checkpoint | `P` | После завершения optimizer step со всеми микробатчами |
| Продолжить | `R` | Из состояния «На паузе» |
| Сохранить без остановки | `S` | На ближайшей безопасной границе |
| Сохранить и выйти | `Q` / `Ctrl+C` | После завершения текущей работы на границе шага |

При узком терминале кнопки переходят в вертикальную компоновку, содержимое
прокручивается. Завершённая панель остаётся открытой до `Q`.
Во время записи конфликтующие действия блокируются. Запрошенный выход не разрывает
запись посередине. Вызов MLX и целиком идущая подготовка кэша/validation не прерываются
внутри вычисления: интерфейс принимает запрос, а движок обрабатывает его на границе.

**Как читать показатели:**

- Общий процент считается из реального числа запланированных optimizer steps.
- Неизвестный объём этапа обозначается `⋯`, недоступное измерение — `н/д`.
- ETA появляется после трёх шагов текущей группы, исключает паузу и сбрасывается
  при смене этапа. Это экстраполяция скорости, без будущего cache/validation/save I/O.
- MLX active/peak и RSS/peak процесса показаны отдельно. Их нельзя складывать:
  в общей памяти измерения могут пересекаться.
- Время последнего успешного checkpoint и папка запуска доступны прямо в панели.

Без TTY автоматически используется plain-режим. Полная история шагов остаётся в
`metrics.jsonl`, даже если консоль выводит только часть обновлений.

## Как это работает

![Прямой проход и градиент через блоки](https://gitlab.com/salyukov.gleb033/sloy_ai/-/raw/main/docs/assets/architecture.png)

Модель разбивается на последовательные единицы: **embedding + позиции → Transformer
блоки → normalization + LM head**. Голова и embedding тоже участвуют в расписании,
чтобы обучение с нуля не оставляло их случайными.

1. Планировщик выбирает непрерывную группу. Её веса размораживаются, остальные — нет.
2. Замороженный префикс вычисляет представления. Их можно сохранить и повторно читать.
3. Обучаемая группа и замороженный суффикс вычисляют logits и cross-entropy.
4. Градиент проходит **через суффикс к группе**. Замораживание весов суффикса
   не отменяет backward по его входам и память промежуточных вычислений.
5. Микробатчи накапливают взвешенные градиенты. После единого Adam update и `mx.eval`
   можно безопасно сохранять, останавливаться или менять группу.

Состояния Adam неактивных групп выгружаются на диск. `stop_gradient` применяется
только к замороженному префиксу. Кэш при смене группы проверяется по SHA256 весов
префикса, данных, версии tokenizer и контекста, затем при необходимости перестраивается.

| `mode` | Что обучается | Для чего |
|---|---|---|
| `baseline` | Все веса каждый шаг | Контроль качества и стоимости |
| `sequential` | Соседние группы по очереди | Простой воспроизводимый порядок |
| `adaptive` | Группы по эвристике loss/time с исследованием | Эксперимент; преимущество не гарантировано |

`cache: auto` включает кэш только при положительной оценке амортизации.
`cache: on` принудительно строит его для сравнения, `off` отключает.
Переиспользование может оказаться дороже свежего вычисления — особенно на маленькой модели.

Подробнее: [архитектура и инварианты](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/architecture.md).

## Настройка обучения

Полный пример находится в созданном `tiny.yaml`. Путь `data` разрешается относительно
этого YAML, а не текущей рабочей папки.

```yaml
name: my-small-lm
data: corpus.txt
seed: 42
context: 32
dim: 48
heads: 4
layers: 3

epochs: 2
max_steps: 40
batch_size: 8
microbatch: 2
learning_rate: 0.003

mode: sequential
group_size: 1
stage_steps: 8
cache: auto
memory_budget_gb: 4
auto_microbatch: true

validation_every: 8
best_metric: validation_loss
save_every: 16
save_seconds: 300
keep_checkpoints: 3
device: gpu
```

`batch_size` — число окон на обновление оптимизатора; `microbatch` — сколько окон
считается одновременно. Уменьшение микробатча увеличивает число накоплений, сохраняя
эффективный batch. `context` измеряется в **байтах**, не в словах.

Пробник проверяет 1, 2, 4… окна до `batch_size` в отдельных процессах. Выбирает
наибольший прошедший вариант с запасом 25%, резервом 2 GiB общей RAM для ОС и
512 MiB текущей available memory. **Контекст автоматически не уменьшается.**
Бюджет — ориентир, не системный лимит и не гарантия отсутствия OOM или swap.

[Полный справочник параметров](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/configuration.md)

## Сохранить сейчас, продолжить позже

```bash
# Последняя исправная версия; повреждение latest явно пишется в лог.
sloy resume --run runs/first

# Строго указанная версия; подмена другим checkpoint не выполняется.
sloy resume --checkpoint runs/first/checkpoints/step-00000016-<id>

# Последняя модель или лучшая по выбранной метрике.
sloy export --run runs/first --output exports/latest
sloy export --run runs/first --output exports/best --best
```

Checkpoint включает веса, Adam, состояние постоянного LR, шаги/токены/эпоху,
позицию и перемешивание данных, NumPy/Python/MLX RNG, выбранную группу, scheduler,
конфигурацию, tokenizer, hash данных, метрики и накопленные часы. Кэш можно построить заново.

Запись идёт во временную папку: **файлы → checksums → проверка → rename → latest**.
Минимум две исправные версии сохраняются, best закрепляется отдельно. Нехватка места
не удаляет предыдущую исправную копию. Изменённые данные или несовместимая конфигурация
вызывают ошибку, а не скрытое начало нового обучения.

```text
runs/first/
├── config.json             # зафиксированные параметры
├── provenance.json         # tokenizer, данные, версия MLX
├── probe.json              # замер и выбранный microbatch, если пробник включён
├── run.log                 # сообщения с временем и уровнем
├── metrics.jsonl           # метрики законченных шагов
├── summary.json            # итог при нормальном завершении
├── checkpoints/
│   ├── latest.json
│   ├── best.json
│   └── step-00000016-<id>/  # веса + optimizer + RNG + manifest + state
├── optimizer-bank/         # рабочие состояния неактивных групп
└── cache/                  # восстанавливаемые представления префикса
```

При внезапном отключении питания или SIGKILL восстановление ограничено последней
исправной записью. Экспорт модели — не checkpoint для `resume`.

[Руководство по сохранению и восстановлению](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/checkpoints.md)

## Python API

### Обучение без терминального интерфейса

```python
from sloy_AI import train
from sloy_AI.config import Config
from sloy_AI.probe import tune

config = Config.load("my-first-model/tiny.yaml")
config, probe_report = tune(config)  # явный подбор для Python API
engine = train(config, run="runs/python-example")
print(engine.run)
```

Прямой `Engine` использует уже заданный microbatch; `auto_microbatch` автоматически
обрабатывает CLI. Для управления из другого потока используйте `Controller`.

### Загрузка и генерация

```python
from sloy_AI.inference import load_export, generate

model, config = load_export("exports/best")
text = generate(model, config, "The ", max_bytes=80)
print(text)
```

Генерация greedy и байтовая: маленькая модель после короткого примера ещё не обязана
создавать связный текст. Некорректные UTF-8 последовательности декодируются с заменой.

[API и интеграция с приложением](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/python-api.md)

## Что показывают измерения

![Память, время и качество четырёх методов](https://gitlab.com/salyukov.gleb033/sloy_ai/-/raw/main/docs/assets/benchmark.png)

Короткое сравнение: **185 152 параметра · 100 шагов · 25 120 токенов · context 32 ·
effective batch 8 · 3 повтора** на метод. Ниже средние; меньше — лучше.

| Метод | MLX peak, MiB | RSS peak, MiB | Wall, с | Validation CE |
|---|---:|---:|---:|---:|
| Все веса | 18.42 | 75.25 | 1.698 | **2.1104** |
| По очереди, без кэша | **15.44** | **67.16** | 1.413 | 2.3092 |
| По очереди, кэш on | **15.44** | 72.17 | 2.064 | 2.3092 |
| Adaptive, кэш auto | **15.44** | 70.38 | **1.331** | 2.2625 |

В этом workload блочные методы уменьшили измеренный пик MLX примерно на **16.2%**,
но уступили baseline по качеству. Принудительный кэш замедлил запуск; auto его не
включил. Wall включает процесс, кэш, validation и сохранения. Из-за короткой
длительности и разброса это не доказательство устойчивого ускорения.

![Изменение train loss в первых повторах](https://gitlab.com/salyukov.gleb033/sloy_ai/-/raw/main/docs/assets/training.png)

Команда из корня клонированного репозитория:

```bash
sloy benchmark --config examples/benchmark.yaml --output runs/comparison --repeats 3
```

[Методика и ограничения замера](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/report.md) ·
[Исходные числа](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/docs/measurements/results.json)

## Ограничения и частые вопросы

**Можно ли загрузить любую внешнюю модель?** Нет. В 0.2 поддерживается только
собственный Transformer, float32, фиксированные окна и UTF-8 byte tokenizer.
LoRA, quantization, dropout и распределённое обучение пока не реализованы.

**Почему маленький microbatch не гарантирует отсутствие OOM?** В памяти остаются
веса, активные состояния, градиенты и вычисления суффикса. Корпус и окна также
загружаются в RAM. ОС и другие программы делят доступную память.

**Можно изменить YAML перед resume?** Для продолжения с тем же состоянием нужна
совместимая конфигурация. Изменение архитектуры, данных и формата tokenizer — новый
эксперимент. Ошибки совместимости описаны в журнале.

**Будут ли результаты побитово одинаковыми?** Не гарантируется. Короткий тест
сравнивает resume с непрерывным запуском при `atol=rtol=2e-5`. Долгие GPU-запуски
могут расходиться; adaptive дополнительно зависит от измеренного времени.

**Почему не открылась панель?** Проверьте TTY. Перенаправление вывода, неинтерактивный
stdin или `--plain` включают простой режим. При недоступном GPU движок сообщает ошибку;
скрытого перехода на CPU нет.

## Разработка и лицензия

```bash
python -m pip install -e '.[test,docs,release]'
pytest -q
python scripts/render_docs.py
python -m build
python -m twine check --strict dist/*
```

[Как внести вклад](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/CONTRIBUTING.md) ·
[История версий](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/CHANGELOG.md) ·
[Сообщить о проблеме](https://gitlab.com/salyukov.gleb033/sloy_ai/-/issues)

Код распространяется по **MIT**. MLX, Textual и другие зависимости сохраняют свои
лицензии и copyright notices: [LICENSE](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/LICENSE),
[THIRD_PARTY_NOTICES](https://gitlab.com/salyukov.gleb033/sloy_ai/-/blob/main/THIRD_PARTY_NOTICES.md).
