---
docgen:
  source: npm/lib/omlx.mjs
  crc: e29efc97
---

# omlx

## Огляд

Спільний транспорт до локального omlx-сервера (OpenAI-сумісний MLX-inference на `http://127.0.0.1:8000/v1/chat/completions`). Text-only: сервер не підтримує інструменти, тож модуль шле лише повідомлення й читає текст відповіді.

## Поведінка

1. Виклик будує запит з повідомленнями, моделлю, температурою і лімітом виходу; model-id з префіксом `omlx/` нормалізується до чистого імені, порожній — замінюється дефолтною моделлю (`mlx-community--gemma-4-e2b-it-4bit`, override через `N_CURSOR_OMLX_MODEL`).
2. Endpoint береться з `N_CURSOR_OMLX_URL` або дефолтний.
3. Якщо на сервері ввімкнено API-ключ, він резолвиться в порядку: явний параметр виклику → `N_CURSOR_OMLX_KEY` → поле `auth.api_key` з локального `~/.omlx/settings.json` (читання fail-safe) — і шлеться як `Authorization: Bearer`. Без знайденого ключа заголовок не додається.
4. Тимчасові обриви з'єднання (передача перервана, порожня відповідь, збій прийому) ретраяться до трьох спроб; решта помилок — виняток одразу.
5. Помилка API у тілі відповіді, невалідний JSON чи порожній контент — виняток із діагностичним префіксом `omlx …`.

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

- `callOmlx` — синхронний chat-виклик, повертає непорожній текст відповіді.
- `isOmlxModel` / `omlxModelId` — перевірка і зняття префікса `omlx/`.
- `resolveOmlxApiKey` — резолвінг API-ключа за описаним порядком джерел.
- `DEFAULT_OMLX_URL` / `DEFAULT_OMLX_MODEL` — дефолти endpoint і моделі.

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

- Жодних `tools`/`tool_calls` у запиті — сумісність із text-only сервером.
- Ролі повідомлень (`system`/`user`) передаються без злиття.
- Виняток ніколи не ковтається: викликач завжди дізнається про збій.
