@7n/llm-lib 2.9.9 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [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,31 +3,31 @@ 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: 16df44f1
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
-  issues: judge-refine:kept-original,judge:inaccurate:0.97
+  issues: judge-refine:kept-original,judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Модуль централізує вибір і нормалізацію LLM-моделей для local та cloud tier значень. Він дає спільну точку для розбору і форматування model spec, визначення локальності моделі та зіставлення tier із рівнем thinking.
+Публічний шар модуля зосереджений на виборі та нормалізації моделей: `resolveModel`, `parseModelId`, `formatModelSpec`, `isLocalModel`, `thinkingLevelForTier` і константах `LOCAL_MIN`, `LOCAL_AVG`, `LOCAL_MAX`, `CLOUD_MIN`, `CLOUD_AVG`, `CLOUD_MAX`.
 
-## Поведінка
+Він узгоджує представлення моделі між tier і форматом `"provider/model-id"`, дає змогу відрізняти локальні моделі від хмарних і окремо пов’язує tier із рівнем thinking.
 
-Модуль задає спільну env-політику вибору моделей через LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX. Ці значення є вхідним станом для подальшого резолву та класифікації: порожнє значення означає, що відповідний tier не заданий явно.
+## Поведінка
 
-resolveModel приймає абстрактний tier і повертає фактичний model spec у форматі pi. Вибір делегується нативному шару, щоб JavaScript-споживачі отримували той самий каскад, що й Rust-частина. Якщо каскад не знаходить явної моделі, результатом стає порожній рядок, який залишає вибір дефолтної моделі нижчому шару.
+LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX — це джерело політики вибору моделі: значення беруться з env і далі використовуються як канонічні тири для розв’язання model-spec та класифікації локальної чи хмарної моделі. Якщо відповідний env не заданий, значення лишається порожнім рядком, тож наступні кроки можуть повернути порожній результат замість конкретної моделі.
 
-parseModelId і formatModelSpec підтримують єдиний формат обміну між конфігурацією, результатами resolveModel і pi-моделями. parseModelId відкидає некоректні або неповні model spec, а formatModelSpec перетворює фактично вибрану pi-модель назад у той самий текстовий формат для подальшого порівняння чи логування.
+resolveModel — центральна точка для отримання фактичного `"provider/model-id"` за абстрактним тиром. Вона спирається на канон тиру з native-шару, а невідомий тир відсікає одразу тут, щоб зберегти TypeError на рівні цього модуля. Результат або повертає готовий model-spec, або порожній рядок, якщо дефолт не визначений.
 
-isLocalModel використовує спільні LOCAL_* значення та список локальних провайдерів з оточення, щоб визначити, чи фактично вибрана або явно задана модель є локальною. Для цього результат resolveModel або formatModelSpec може бути переданий у isLocalModel після нормалізації через спільний формат.
+parseModelId і formatModelSpec утворюють парну нормалізацію між рядковим spec та об’єктом моделі: перша розкладає зовнішній `"provider/model-id"` на складники, друга збирає фактично резолвлену модель назад у той самий формат. Це дозволяє пропускати через модуль як сирі spec-рядки, так і вже вибрані pi-моделі без втрати форми.
 
-thinkingLevelForTier працює з rung-рівнями escalation-ланцюжка й повертає дискретний рівень thinking для виконання запиту. Це рішення незалежне від env-конфігурації моделей, але використовується поруч із resolveModel у потоках, де одночасно обираються модельний tier і інтенсивність міркування.
+isLocalModel використовує спільні тири LOCAL_MIN, LOCAL_AVG і LOCAL_MAX як найвищий пріоритет, а для решти spec опирається на провайдера з `N_LLM_LOCAL_PROVIDERS`. Так модуль узгоджує явні локальні політики з ознакою провайдера й дає один бінарний сигнал для ланцюжків, що відрізняють local від cloud.
 
-Файл не виконує власних операцій запису у ФС чи БД; результати передаються назовні як значення для споживачів LLM-шару. Імпортовані модулі не аналізувались.
+thinkingLevelForTier не бере участі у резолву моделі, але працює поруч із тирами як окрема проєкція: перетворює rung-рівні на дискретний thinkingLevel для downstream-логіки. Це тримає вибір моделі та рівень міркування синхронними, але розділеними по відповідальності.
 
 ## Публічний API
 
@@ -55,7 +55,11 @@ 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-заголовки.
 
 ## Гарантії поведінки

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.0",
   "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",