---
docgen:
  source: npm/lib/llm.mjs
  crc: 9ef9f20f
---

# llm

## Огляд

Єдина точка LLM-викликів для JS-оркестраторів монорепо: ховає вибір транспорту за конвенцією префікса model-id і дає preflight-перевірку локального сервера перед масовими прогонами.

## Поведінка

1. Виклик із model-id з префіксом `omlx/` іде прямим HTTP до локального omlx-сервера зі збереженням ролей повідомлень; будь-який інший model-id (зокрема порожній) — через `pi` CLI, де повідомлення конкатенуються в один текстовий промпт, а інструменти вимкнено.
2. Якщо виставлено `N_CURSOR_LLM_TRACE` зі шляхом до файлу, кожен виклик дописує один JSONL-рядок: бекенд, модель, тривалість, розміри промпта/відповіді, успіх або текст помилки. Невдалий запис трейсу не впливає на сам виклик.
3. Preflight локального сервера робить мінімальний запит (одна позиція виходу) і класифікує стан: сервер лежить (`down`), модель не влазить у динамічну стелю пам'яті зайнятої машини (`memory-guard`), сервер вимагає API-ключ (`auth`), інша помилка (`error`). Порожня відповідь живого сервера вважається здоровим станом.

## Публічний API

- `callLlm` — універсальний виклик за messages-масивом із маршрутизацією за префіксом model-id.
- `pickBackend` — назва бекенда (`omlx` чи `pi`) для заданого model-id.
- `omlxHealthCheck` — preflight-стан локального сервера: `{ ok, reason, detail }`.

## Гарантії поведінки

- Маршрутизація залежить лише від рядка моделі — жодних env-перемикачів бекенда.
- Помилка транспорту прокидається винятком; трейс при цьому фіксує невдачу.
- `memory-guard` означає «машина зайнята, спробуй пізніше», а не дефект моделі чи конвеєра.
