# llama-decision — Bosun v3.1 0.6B (decision-модель ai-router)

llama.cpp-сайдкар с одной узкой задачей: readout decision-модели
[Bosun v3.1 0.6B](https://huggingface.co/Hanno-Labs/bosun-v3.1-0.6b-GGUF)
(Apache 2.0). Bosun — не чат-модель: она отвечает на типизированные вопросы
(choice / score / noul) вероятностью по вариантам, с калиброванным conf.
Readout требует `n_probs` (top-k логиты) нативного `/completion` llama.cpp —
ollama распределение не отдаёт, поэтому отдельный контейнер.

Клиент — `services/ai-router/pkg/decision` (рендер промпта, масочный softmax
по top-k с консервативным хвостом). Потребители: гейты классификации ai-router.

## Установка GGUF (вручную, один раз)

llama.cpp не умеет скачивать модели. Файл кладётся в `./llama-decision/models/`
рядом с compose (каталог вне git):

```bash
cd /opt/unishift/llama-decision/models/   # каталог на сервере
curl -L -o bosun-v3.1-0.6b-Q8_0.gguf \
  https://huggingface.co/Hanno-Labs/bosun-v3.1-0.6b-GGUF/resolve/main/bosun-v3.1-0.6b-Q8_0.gguf
python3 patch_gguf.py bosun-v3.1-0.6b-Q8_0.gguf   # скрипт из этого каталога
```

**Патч обязателен.** В официальном GGUF decision-токены помечены
`token_type=3` (CONTROL) — llama.cpp-стек прячет их текст и logprobs, readout
не работает. `patch_gguf.py` меняет 256 записей на USER_DEFINED (4),
метаданные only, веса не трогаются. Идемпотентен.

## Включение

```bash
# .env
DECISION_URL=http://llama-decision:8080
# COMPOSE_PROFILES=decision   # или:
docker compose --profile decision up -d llama-decision
# затем рестарт ai-router, чтобы seed создал провайдер capability=decision
```

Env:
- `DECISION_URL`: URL сайдкара для ai-router (например, `http://llama-decision:8080` в docker или `http://127.0.0.1:18088` локально; пусто = выключен).
- `DECISION_MODEL`: имя модели (`bosun-v3.1-0.6b`).
- `DECISION_MODEL_FILE`: имя файла в `/models` (`bosun-v3.1-0.6b-Q8_0-ud.gguf`).
- `DECISION_TIMEOUT`: таймаут запроса (дефолт `10s`, в ai-router `45s`).
- `DECISION_THREADS`: число CPU-потоков compute (дефолт `8`, плато на ~6–8 потоках, дает кратное ускорение prefill по сравнению с дефолтными 2).
- `DECISION_CTX`: общий контекст (дефолт `8192`). Делится между слотами `-np` (при 2 слотах = 4096 токенов на слот, предотвращает `exceed_context_size_error` на 3500 рунах стейта + критериях).
- `DECISION_NP`: параллельные слоты llama-server (дефолт `2`). Должно соответствовать `DECISION_MAX_INFLIGHT` в ai-router.
- `DECISION_FLASH_ATTN`: Flash Attention (дефолт `on`; если на конкретном CPU образ сбоит на старте, выставить `off` или `auto`).
- `DECISION_N_GPU_LAYERS`: слои на GPU (дефолт `0` для CPU; на GPU-хосте выставить `99` для полной выгрузки на видеокарту и уменьшить `DECISION_THREADS` до 2-4).
- `DECISION_PORT`: host-порт (дефолт `18088`). Внимание: в `devops/dev/docker-compose.yaml` порт `18088` по умолчанию занимает SearXNG (`SEARXNG_PORT`). Если запускаете сайдкар параллельно с dev compose, укажите свободный порт (в PM2 SearXNG на `:8088`, а decision на `:18088`).

## Проверка

```bash
curl -s localhost:18088/health
```

Go-интеграционный тест (сервер должен быть запущен, у теста дефолт :18088 —
локальный стенд; для контейнера задай переменную и порт):

```bash
cd services/ai-router && go test ./pkg/decision/ -run TestDecideAgainstLlamaServer -v
```

Локальный стенд без docker (PM2-дев):

```bash
runtime/llama.cpp/build/bin/llama-server -m runtime/models/bosun-v3.1-0.6b-Q8_0-ud.gguf \
  --port 18088 -c 8192 -np 2 -t 8 -fa on
```
