Локальный LLM-стек (local-llm)

Scope: NL-вход к локальному LLM-стеку (установка / запуск / статус / переключение модели) + слой суждения для оценки находок монитора новых моделей. Not in scope: механика (установка, состояния, переключение, архив) — она в детерминированных скриптах (различение «Скрипт ≠ Агент»). Скилл их вызывает, не дублирует логику. Источник истины статусов моделей — каталог + model-lifecycle.py. JOB стека: приватность (задачи с персональными данными, что нельзя слать в облако) + запасной режим (без сети / кончились токены облака). См. ADR-001-local-llm-stack.md.

Расположение бандла

Управляющие скрипты — самодостаточный бандл (каждый работает из своей директории). Путь резолвится через env, дефолт — extensions/local-llm/ внутри IWE-установки:

BUNDLE="${IWE_LOCAL_LLM_DIR:-$HOME/IWE/extensions/local-llm}"

• venv стека: ~/.iwe-local-llm/.venv (ставит установщик).
• Активная модель + состояние сервера: ~/.iwe-local-llm/ (active-model, server.pid, server.log).

When to use

• «поставь / установи локальную модель» → установка под железо (Шаг 1).
• «покажи модели» / «какие модели есть» → список по состояниям (Шаг 2).
• «запусти / останови» / «статус» → управление сервером (Шаг 2).
• «переключи модель» / «переключи на 14B» → смена активной модели (Шаг 3).
• «какие новые модели вышли» / «проверь новые модели» → мониторинг + суждение об adopt (Шаг 4).

Algorithm

Шаг 1 — установка (механика → скрипт)

bash "$BUNDLE/install-local-llm.sh"          # рекомендованная модель под железо
bash "$BUNDLE/install-local-llm.sh" --max    # самая тяжёлая влезающая

Установщик идемпотентен: детект железа → выбор модели из каталога под память → venv + mlx-lm → скачивание → smoke. Показать пользователю итог (модель, что сервер поднялся).

Шаг 2 — запуск / статус / список (механика → скрипт)

bash "$BUNDLE/iwe-local-llm.sh" start    # поднять сервер (OpenAI-совместимый, localhost:8080)
bash "$BUNDLE/iwe-local-llm.sh" status   # активная модель + состояние сервера
bash "$BUNDLE/iwe-local-llm.sh" models   # все модели по четырём состояниям + факт скачивания
bash "$BUNDLE/iwe-local-llm.sh" stop     # остановить сервер
bash "$BUNDLE/iwe-local-llm.sh" test     # проверка совместимого интерфейса (SHIM_OK)

Инструменты IWE подключаются к http://127.0.0.1:8080/v1/chat/completions тем же клиентом, что и к облаку.

Шаг 3 — переключение модели (механика → скрипт)

bash "$BUNDLE/iwe-local-llm.sh" use <model-id>    # скачать + активировать + перезапуск
bash "$BUNDLE/iwe-local-llm.sh" pull <model-id>   # только скачать для тестирования (→ testing)
bash "$BUNDLE/iwe-local-llm.sh" archive <model-id># вывести в архив

use переводит прежнюю активную в testing (остаётся скачанной). Ровно одна активная. Не редактировать model-catalog.yaml руками — только через iwe-local-llm.sh / model-lifecycle.py (сохраняет комментарии, держит инвариант одной active).

Шаг 4 — мониторинг новых моделей (суждение → LLM-работа)

BUNDLE="${IWE_LOCAL_LLM_DIR:-$HOME/IWE/extensions/local-llm}"
PY3="$(bash "${IWE_SCRIPTS:-$HOME/IWE/scripts}/lib/find-python3.sh")" && "$PY3" "$BUNDLE/model-monitor.py"    # дайджест трендовых моделей, которых нет в каталоге

Монитор только находит кандидатов. Решение об adopt — суждение агента (это и есть LLM-работа, ради которой скилл существует):

1. Сравнить кандидата с текущей активной по качеству (LMArena / бенчмарки, если пользователь даёт ссылку или просит свериться).
2. Проверить соответствие JOB: приватность (оффлайн, без телеметрии) + влезает в память Mac (min_ram_gb ≤ железо).
3. Дать рекомендацию: добавить в каталог (model-lifecycle.py add) + pull для сравнения, либо пропустить с причиной.
4. Решение о смене active — за пользователем; скилл предлагает, не переключает молча.

Anti-patterns

• Дублировать механику в скилле. Состояния/переключение/архив — в скриптах. Скилл вызывает, не переписывает (OwnerIntegrity: каталог = источник истины).
• Молча переключать активную модель по находке монитора. Adopt — решение пользователя после сравнения качества.
• Слать содержимое промптов в облако при выборе локального стека под приватность — стек именно для того, чтобы этого не делать.
• Править model-catalog.yaml руками — ломает комментарии и инвариант одной active; только через lifecycle-команды.