@7n/llm-lib 2.9.9 → 2.10.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [2.10.1] - 2026-07-27
+
+### Fixed
+
+- Smoke-тест `resolveModel` через живий napi-аддон стабільний під `bun run --bun vitest`: каскад ганяється в дочірньому процесі з env при spawn, бо Bun не передає записи `process.env` у нативний environ (Rust `env::var` бачив ambient-значення замість `vi.stubEnv`)
+
+## [2.10.0] - 2026-07-27
+
+### Added
+
+- llm-lib: додано litellm як другий local-provider (перемикач omlx/litellm через `N_LOCAL_*_MODEL`, `defaultLocalProviders()` з `N_OMLX_*`/`N_LITELLM_*` env)
+
 ## [2.9.9] - 2026-07-27
 
 ### Fixed

package/lib/docs/index.md

@@ -16,6 +16,7 @@ resource: llm-lib/lib/
 | [chains-report.mjs](chains-report.md)     | JS Module |
 | [harness.mjs](harness.md)                 | JS Module |
 | [local-cloud.mjs](local-cloud.md)         | JS Module |
+| [local-providers.mjs](local-providers.md) | JS Module |
 | [model-tiers.mjs](model-tiers.md)         | JS Module |
 | [one-shot.mjs](one-shot.md)               | JS Module |
 | [prompt-budget.mjs](prompt-budget.md)     | JS Module |

package/lib/docs/local-providers.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: local-providers.mjs
+resource: llm-lib/lib/local-providers.mjs
+docgen:
+  crc: 6513b04f
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Дефолтна мапа local-провайдерів для `llm_lib::local_cloud` у форматі `{ prefix: { baseUrl, apiKey } }`, яку споживають `oneShotLocalCloud` і `submitBatch`.
+
+`omlx` і `litellm` завжди присутні в мапі одночасно, а фактичний виклик іде рівно в один клієнт за `provider`-префіксом у model-spec. Якщо spec не вказує на певний префікс, відповідний запис у мапі не отримує запиту.
+
+## Поведінка
+
+1. `defaultLocalProviders` формує єдиний дефолтний набір local-провайдерів для `llm_lib::local_cloud`, щоб обидва зареєстровані напрямки — `omlx` і `litellm` — були доступні одночасно в очікуваному `{ prefix: { baseUrl, apiKey } }` форматі для `oneShotLocalCloud` і `submitBatch`.
+2. Для `omlx` функція бере `baseUrl` з `N_OMLX_BASE_URL`, а якщо його немає — підставляє `http://127.0.0.1:8000/v1/`; `apiKey` бере з `N_OMLX_API_KEY`, інакше лишає порожнім значенням.
+3. Для `litellm` функція бере `baseUrl` з `N_LITELLM_BASE_URL`, а якщо його немає — підставляє `https://llm.7n.ai/v1/`; `apiKey` бере з `N_LITELLM_API_KEY`, інакше лишає порожнім значенням.
+4. Функція не вирішує, який провайдер “активний” сама по собі: вибір фактично визначається тим, який provider-префікс вказаний у model-spec на кшталт `N_LOCAL_MIN_MODEL`.
+5. Коли model-spec вказує на один префікс, `LocalCloud::one_shot_with_spec` звертається рівно до відповідного клієнта; другий запис у мапі залишається запасним і не отримує запитів, доки жоден spec на нього не посилається.
+
+## Гарантії поведінки
+
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/docs/model-tiers.md

@@ -3,9 +3,9 @@ type: JS Module
 title: model-tiers.mjs
 resource: llm-lib/lib/model-tiers.mjs
 docgen:
-  crc: 13970c1f
-  model: openai-codex/gpt-5.5
-  tier: cloud-avg
+  crc: 05c5eb6a
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
   issues: judge-refine:kept-original,judge:inaccurate:0.97
   judgeModel: openai-codex/gpt-5.4-mini
@@ -13,21 +13,17 @@ docgen:
 
 ## Огляд
 
-Модуль централізує вибір і нормалізацію LLM-моделей для local та cloud tier значень. Він дає спільну точку для розбору і форматування model spec, визначення локальності моделі та зіставлення tier із рівнем thinking.
+`LOCAL_MIN`, `LOCAL_AVG`, `LOCAL_MAX`, `CLOUD_MIN`, `CLOUD_AVG` і `CLOUD_MAX` задають спільні варіанти модельного рівня для локального та хмарного сценаріїв, щоб споживачі використовували однакові значення для вибору режиму роботи. `parseModelId` і `formatModelSpec` узгоджують подання модельного ідентифікатора між внутрішнім представленням і зовнішнім форматом, а `resolveModel` повертає уже погоджений варіант для подальшого використання. `thinkingLevelForTier` фіксує відповідність між tier і рівнем thinking, а `isLocalModel` дає змогу відрізнити локальні моделі від інших без дублювання цієї перевірки в різних місцях.
 
 ## Поведінка
 
-Модуль задає спільну env-політику вибору моделей через LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX. Ці значення є вхідним станом для подальшого резолву та класифікації: порожнє значення означає, що відповідний tier не заданий явно.
+LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX беруть значення з environment на старті модуля та задають єдину політику вибору моделі для локального й хмарного шарів. Ці значення далі слугують опорою для resolveModel, який повертає вже фактично обраний model spec у форматі provider/model-id або порожній рядок, якщо дефолт провайдера лишився substrate-рівню. Невідомий tier відсіюється на цьому рівні як помилка контракту.
 
-resolveModel приймає абстрактний tier і повертає фактичний model spec у форматі pi. Вибір делегується нативному шару, щоб JavaScript-споживачі отримували той самий каскад, що й Rust-частина. Якщо каскад не знаходить явної моделі, результатом стає порожній рядок, який залишає вибір дефолтної моделі нижчому шару.
+thinkingLevelForTier переводить rung-tier у дискретний рівень thinking, щоб downstream-логіка могла узгоджено трактувати силу моделі без повторного аналізу spec. local-min і local-min-retry зводяться до найнижчого рівня, cloud-min, cloud-avg і cloud-max піднімають рівень відповідно до потужності хмарного вибору.
 
-parseModelId і formatModelSpec підтримують єдиний формат обміну між конфігурацією, результатами resolveModel і pi-моделями. parseModelId відкидає некоректні або неповні model spec, а formatModelSpec перетворює фактично вибрану pi-модель назад у той самий текстовий формат для подальшого порівняння чи логування.
+parseModelId і formatModelSpec утворюють парний обмін між рядковим model spec та об’єктом моделі: перший розбирає канонічний рядок на provider та id, другий збирає фактично резолвлену модель назад у той самий формат. Якщо spec або модель неповні, результатом є null, щоб не маскувати malformed або відсутній стан.
 
-isLocalModel використовує спільні LOCAL_* значення та список локальних провайдерів з оточення, щоб визначити, чи фактично вибрана або явно задана модель є локальною. Для цього результат resolveModel або formatModelSpec може бути переданий у isLocalModel після нормалізації через спільний формат.
-
-thinkingLevelForTier працює з rung-рівнями escalation-ланцюжка й повертає дискретний рівень thinking для виконання запиту. Це рішення незалежне від env-конфігурації моделей, але використовується поруч із resolveModel у потоках, де одночасно обираються модельний tier і інтенсивність міркування.
-
-Файл не виконує власних операцій запису у ФС чи БД; результати передаються назовні як значення для споживачів LLM-шару. Імпортовані модулі не аналізувались.
+isLocalModel використовує ту саму політику, що й resolveModel: спочатку звіряє явні локальні тири, а потім визначає локальність за provider із model spec. Це дає спільне правило для агрегатів local/cloud і для рішень, де потрібно відрізнити локальний шлях від хмарного без дублювання логіки в consumers.
 
 ## Публічний API
 
@@ -55,9 +51,17 @@ cloud-min — `medium`, cloud-avg — `high`, cloud-max (experiment-only tier,
 pi-моделі (`session.model`), коли consumer лишив `modelSpec` порожнім і pi
 сам вибрав дефолт (локальний чи хмарний).
 - isLocalModel — Чи model-spec вказує на локальну модель: збіг з одним із LOCAL_* тирів
-АБО провайдер з `N_LLM_LOCAL_PROVIDERS` (дефолт `omlx`). Використовується
+АБО провайдер з `N_LLM_LOCAL_PROVIDERS` (дефолт `omlx,litellm`). Обидва
+провайдери можуть бути зареєстровані в `localProviders`-конфізі одночасно
+(див. `local-providers.mjs`) — "активний" завжди рівно один, бо
+`LocalCloud` викликає клієнта за провайдер-префіксом фактичного
+model-spec, не за наявністю запису в мапі. Використовується
 для local/cloud-агрегатів ланцюжків і рішення про chain-заголовки.
 
+## Сценарії використання
+
+- `llm-lib/tests/model-tiers.test.mjs` (isLocalModel; parseModelId) — omlx-провайдер — локальний (дефолт N_LLM_LOCAL_PROVIDERS); litellm-провайдер — теж локальний за дефолтом (перемикач omlx/litellm через тир-env); порожній/malformed spec — не локальний; кастомний список провайдерів через env (ізольований re-import); звичайна пара; ще 8
+
 ## Гарантії поведінки
 
 - Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/local-providers.mjs

@@ -0,0 +1,31 @@
+/**
+ * Дефолтна мапа local-провайдерів для Rust-крейта `llm_lib::local_cloud`
+ * (той самий `{ prefix: { baseUrl, apiKey } }` конфіг, що приймає
+ * `oneShotLocalCloud`/`submitBatch`). Обидва зареєстровані провайдери
+ * (`omlx`, `litellm`) завжди присутні в мапі одночасно — "активність"
+ * визначається лише тим, чий provider-префікс реально стоїть у
+ * model-spec (`N_LOCAL_MIN_MODEL` тощо): `LocalCloud::one_shot_with_spec`
+ * б'є рівно в один клієнт за префіксом spec, тож другий запис у мапі
+ * ніколи не отримує запиту, поки на нього не вказує жоден spec.
+ */
+import { env } from 'node:process'
+
+/**
+ * @returns {{
+ *   omlx: { baseUrl: string, apiKey: string|null },
+ *   litellm: { baseUrl: string, apiKey: string|null }
+ * }} дефолтна мапа локальних провайдерів (override окремих полів — через
+ * `N_OMLX_BASE_URL`/`N_OMLX_API_KEY`/`N_LITELLM_BASE_URL`/`N_LITELLM_API_KEY`)
+ */
+export function defaultLocalProviders() {
+  return {
+    omlx: {
+      baseUrl: env.N_OMLX_BASE_URL ?? 'http://127.0.0.1:8000/v1/',
+      apiKey: env.N_OMLX_API_KEY ?? null
+    },
+    litellm: {
+      baseUrl: env.N_LITELLM_BASE_URL ?? 'https://llm.7n.ai/v1/',
+      apiKey: env.N_LITELLM_API_KEY ?? null
+    }
+  }
+}

package/lib/model-tiers.mjs

@@ -107,7 +107,7 @@ export function formatModelSpec(model) {
 
 /** Провайдери, що вважаються локальними. Override: `N_LLM_LOCAL_PROVIDERS` (кома-список). */
 const LOCAL_PROVIDERS = new Set(
-  (env.N_LLM_LOCAL_PROVIDERS ?? 'omlx')
+  (env.N_LLM_LOCAL_PROVIDERS ?? 'omlx,litellm')
     .split(',')
     .map(p => p.trim())
     .filter(Boolean)
@@ -115,7 +115,11 @@ const LOCAL_PROVIDERS = new Set(
 
 /**
  * Чи model-spec вказує на локальну модель: збіг з одним із LOCAL_* тирів
- * АБО провайдер з `N_LLM_LOCAL_PROVIDERS` (дефолт `omlx`). Використовується
+ * АБО провайдер з `N_LLM_LOCAL_PROVIDERS` (дефолт `omlx,litellm`). Обидва
+ * провайдери можуть бути зареєстровані в `localProviders`-конфізі одночасно
+ * (див. `local-providers.mjs`) — "активний" завжди рівно один, бо
+ * `LocalCloud` викликає клієнта за провайдер-префіксом фактичного
+ * model-spec, не за наявністю запису в мапі. Використовується
  * для local/cloud-агрегатів ланцюжків і рішення про chain-заголовки.
  * @param {string} spec `"provider/model-id"`
  * @returns {boolean} true — локальна модель

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.9.9",
+  "version": "2.10.1",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",
@@ -36,6 +36,7 @@
     "./anchored-edit": "./lib/anchored-edit.mjs",
     "./web-tools": "./lib/web-tools.mjs",
     "./model-tiers": "./lib/model-tiers.mjs",
+    "./local-providers": "./lib/local-providers.mjs",
     "./acp": "./lib/acp.mjs",
     "./local-cloud": "./lib/local-cloud.mjs",
     "./batch": "./lib/batch.mjs",