@7n/llm-lib 2.10.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [2.11.0] - 2026-07-27
+
+### Added
+
+- `submitBatch` тепер обирає між клієнтською емуляцією і справжнім `/v1/batches` litellm batch-adapter-а (`backend: 'auto'|'emulated'|'openai-batches'`) — автоматично вмикається, коли резолвлений провайдер `litellm` і адаптер відповідає на capability-пробу.
+
+## [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

package/lib/batch.mjs

@@ -1,14 +1,18 @@
 /**
- * Тип 2b (OpenAI-сумісний API, batch) — **лише емуляція** у v1 (рішення Р,
- * задача T6): чанкований конкурентний прогін через Тип 2a
- * (`llm_lib::local_cloud`) під інтерфейсом `submit → progress → results` —
- * той самий інтерфейс, яким говорив би й справжній OpenAI Batch API
- * (`/v1/batches`, v2), якому локальний omlx (перший споживач) не має.
+ * Тип 2b (OpenAI-сумісний API, batch) — `submitBatch` обирає між клієнтською
+ * емуляцією (v1, чанкований конкурентний прогін через Тип 2a
+ * `llm_lib::local_cloud`) і справжнім `/v1/batches` litellm batch-adapter-а
+ * (спека `docs/specs/2026-07-27-batch-local-avg-real-batches.md`), під тим
+ * самим інтерфейсом `submit → progress → results` для обох. Вибір —
+ * `backend` (дефолт `'auto'`: реальний Batch API лише коли резолвлений
+ * провайдер `litellm` і кешована мережева проба адаптера пройшла; локальний
+ * omlx завжди йде емуляцією).
  *
- * Тонкий JS-клієнт до Rust-крейта `llm_lib::batch` через napi FFI
- * in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного чанкінгу
- * тут (анти-приклад, якого це узагальнює: `mlmail/use-summary.js` чанкує
- * переклади проти omlx вручну, з вистражданими лімітами).
+ * Тонкий JS-клієнт до Rust-крейта `llm_lib::batch`/`llm_lib::remote_batch`
+ * через napi FFI in-process (`llm-lib/crates/llm-lib-napi`) — жодного
+ * власного чанкінгу чи HTTP тут (анти-приклад, якого це узагальнює:
+ * `mlmail/use-summary.js` чанкує переклади проти omlx вручну, з
+ * вистражданими лімітами).
  */
 import { loadNative } from './internal/native.mjs'
 
@@ -23,9 +27,9 @@ import { loadNative } from './internal/native.mjs'
  */
 
 /**
- * Емуляція batch-виклику Типу 2b. `modelSpecOrTier` — той самий контракт,
- * що й у [`oneShotLocalCloud`] з `local-cloud.mjs`: явний
- * `"provider/model-id"` або абстрактний тир (`min`/`avg`/`max`).
+ * Batch-виклик Типу 2b. `modelSpecOrTier` — той самий контракт, що й у
+ * [`oneShotLocalCloud`] з `local-cloud.mjs`: явний `"provider/model-id"`
+ * або абстрактний тир (`min`/`avg`/`max`).
  * @param {string} modelSpecOrTier `"provider/model-id"` або `'min'|'avg'|'max'`
  * @param {BatchItem[]} items вхідні items (`customId` — унікальний у межах виклику)
  * @param {{
@@ -33,6 +37,9 @@ import { loadNative } from './internal/native.mjs'
  *   system?: string,
  *   chunkSize?: number,
  *   concurrency?: number,
+ *   backend?: 'emulated' | 'openai-batches' | 'auto',
+ *   pollIntervalMs?: number,
+ *   pollTimeoutMs?: number,
  *   onProgress?: (completed: number, total: number) => void,
  *   native?: {
  *     submitBatch: (
@@ -43,13 +50,13 @@ import { loadNative } from './internal/native.mjs'
  *       onProgress?: (completed: number, total: number) => void
  *     ) => Promise<BatchResult[]>
  *   }
- * }} [options] конфіг локальних провайдерів, ліміти чанка/конкурентності, progress-колбек, інжект `native` для тестів
+ * }} [options] конфіг локальних провайдерів, ліміти чанка/конкурентності/бекенда/опитування, progress-колбек, інжект `native` для тестів
  * @returns {Promise<BatchResult[]>} результати в тому самому порядку, що й вхідні `items`
  */
 export function submitBatch(
   modelSpecOrTier,
   items,
-  { localProviders, system, chunkSize, concurrency, onProgress, native } = {}
+  { localProviders, system, chunkSize, concurrency, backend, pollIntervalMs, pollTimeoutMs, onProgress, native } = {}
 ) {
   const nativeImpl = native ?? loadNative()
   return nativeImpl.submitBatch(
@@ -65,7 +72,10 @@ export function submitBatch(
     },
     {
       chunkSize: chunkSize ?? undefined,
-      concurrency: concurrency ?? undefined
+      concurrency: concurrency ?? undefined,
+      backend: backend ?? undefined,
+      pollIntervalMs: pollIntervalMs ?? undefined,
+      pollTimeoutMs: pollTimeoutMs ?? undefined
     },
     onProgress ?? undefined
   )

package/lib/docs/batch.md

@@ -3,7 +3,7 @@ type: JS Module
 title: batch.mjs
 resource: llm-lib/lib/batch.mjs
 docgen:
-  crc: 4412e8c2
+  crc: 5e13af10
   model: openai-codex/gpt-5.4-mini
   tier: cloud-min
   score: 100
@@ -12,22 +12,40 @@ docgen:
 
 ## Огляд
 
-Тонкий JS-клієнт до `llm_lib::batch` у `llm-lib/crates/llm-lib-napi`, який через in-process `napi FFI` лише емулює Type 2b у v1: під одним `submit → progress → results` інтерфейсом він прокидає batch-запит у `llm_lib::local_cloud` і повертає результат як сумісний OpenAI Batch API-контракт для майбутнього `/v1/batches`. Єдина публічна точка входу — `submitBatch`. Це узагальнення анти-прикладу на кшталт `mlmail/use-summary.js`, де чанкінг доводиться робити вручну під обмеження провайдера.
+Тип 2b (OpenAI-сумісний API, batch) — `submitBatch` обирає між клієнтською
+емуляцією (v1, чанкований конкурентний прогін через Тип 2a
+`llm_lib::local_cloud`) і справжнім `/v1/batches` litellm batch-adapter-а
+(спека `docs/specs/2026-07-27-batch-local-avg-real-batches.md`), під тим
+самим інтерфейсом `submit → progress → results` для обох. Вибір —
+`backend` (дефолт `'auto'`: реальний Batch API лише коли резолвлений
+провайдер `litellm` і кешована мережева проба адаптера пройшла; локальний
+omlx завжди йде емуляцією).
+
+Тонкий JS-клієнт до Rust-крейта `llm_lib::batch`/`llm_lib::remote_batch`
+через napi FFI in-process (`llm-lib/crates/llm-lib-napi`) — жодного
+власного чанкінгу чи HTTP тут (анти-приклад, якого це узагальнює:
+`mlmail/use-summary.js` чанкує переклади проти omlx вручну, з
+вистражданими лімітами).
 
 ## Поведінка
 
-1. `submitBatch` приймає batch-запит для Type 2b і передає його в native-реалізацію, щоб отримати той самий бізнес-інтерфейс `submit → progress → results`, який очікується від batch-потоку поверх локальних провайдерів.
-2. `submitBatch` зберігає порядок вхідних items у результатах, щоб кожен результат можна було зіставити з початковим `customId`.
-3. `submitBatch` нормалізує вхідні items перед передачею далі: бере `customId` і `prompt` як є, а відсутній `system` не підміняє значенням.
-4. `submitBatch` передає конфіг локальних провайдерів, загальний `system`, а також ліміти chunking і concurrency у native-шар, щоб контроль виконання залишався в реалізації batch-крейта.
-5. `submitBatch` підтримує `onProgress`, щоб викликати повідомлення про хід виконання під час обробки batch-у.
-6. `submitBatch` дозволяє підмінити native-реалізацію для тестів, не змінюючи зовнішню поведінку публічного API.
+submitBatch повертає результати в тому ж порядку, що й вхідні items; для кожного item результат містить або `ok`, або `error`.
+
+Для кожного item `customId` має бути унікальним у межах одного виклику; конфлікт ідентифікаторів лишається на стороні викликача.
+
+За помилок виконання batch у відповіді зберігається один результат на кожен вхідний item, тож користувацький контракт не зводиться до часткової втрати елементів.
+
+`onProgress`, якщо заданий, отримує агрегований прогрес виконання для всього набору items.
 
 ## Публічний API
 
-- submitBatch — Емуляція batch-виклику Типу 2b. `modelSpecOrTier` — той самий контракт,
-що й у [`oneShotLocalCloud`] з `local-cloud.mjs`: явний
-`"provider/model-id"` або абстрактний тир (`min`/`avg`/`max`).
+- submitBatch — Batch-виклик Типу 2b. `modelSpecOrTier` — той самий контракт, що й у
+[`oneShotLocalCloud`] з `local-cloud.mjs`: явний `"provider/model-id"`
+або абстрактний тир (`min`/`avg`/`max`).
+
+## Сценарії використання
+
+- `llm-lib/tests/batch.test.mjs` (submitBatch) — делегує modelSpecOrTier/items у native.submitBatch і віддає його результат; явний; кожен item нормалізується до {customId, prompt, system}, навіть без власного system; localProviders/system/chunkSize/concurrency прокидаються в options/config; onProgress прокидається останнім аргументом; ще 2
 
 ## Гарантії поведінки
 

package/lib/docs/model-tiers.md

@@ -3,31 +3,27 @@ type: JS Module
 title: model-tiers.mjs
 resource: llm-lib/lib/model-tiers.mjs
 docgen:
-  crc: 16df44f1
+  crc: 05c5eb6a
   model: openai-codex/gpt-5.4-mini
   tier: cloud-min
   score: 100
-  issues: judge-refine:kept-original,judge:inaccurate:0.98
+  issues: judge-refine:kept-original,judge:inaccurate:0.97
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Публічний шар модуля зосереджений на виборі та нормалізації моделей: `resolveModel`, `parseModelId`, `formatModelSpec`, `isLocalModel`, `thinkingLevelForTier` і константах `LOCAL_MIN`, `LOCAL_AVG`, `LOCAL_MAX`, `CLOUD_MIN`, `CLOUD_AVG`, `CLOUD_MAX`.
-
-Він узгоджує представлення моделі між tier і форматом `"provider/model-id"`, дає змогу відрізняти локальні моделі від хмарних і окремо пов’язує tier із рівнем thinking.
+`LOCAL_MIN`, `LOCAL_AVG`, `LOCAL_MAX`, `CLOUD_MIN`, `CLOUD_AVG` і `CLOUD_MAX` задають спільні варіанти модельного рівня для локального та хмарного сценаріїв, щоб споживачі використовували однакові значення для вибору режиму роботи. `parseModelId` і `formatModelSpec` узгоджують подання модельного ідентифікатора між внутрішнім представленням і зовнішнім форматом, а `resolveModel` повертає уже погоджений варіант для подальшого використання. `thinkingLevelForTier` фіксує відповідність між tier і рівнем thinking, а `isLocalModel` дає змогу відрізнити локальні моделі від інших без дублювання цієї перевірки в різних місцях.
 
 ## Поведінка
 
-LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX — це джерело політики вибору моделі: значення беруться з env і далі використовуються як канонічні тири для розв’язання model-spec та класифікації локальної чи хмарної моделі. Якщо відповідний env не заданий, значення лишається порожнім рядком, тож наступні кроки можуть повернути порожній результат замість конкретної моделі.
-
-resolveModel — центральна точка для отримання фактичного `"provider/model-id"` за абстрактним тиром. Вона спирається на канон тиру з native-шару, а невідомий тир відсікає одразу тут, щоб зберегти TypeError на рівні цього модуля. Результат або повертає готовий model-spec, або порожній рядок, якщо дефолт не визначений.
+LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX беруть значення з environment на старті модуля та задають єдину політику вибору моделі для локального й хмарного шарів. Ці значення далі слугують опорою для resolveModel, який повертає вже фактично обраний model spec у форматі provider/model-id або порожній рядок, якщо дефолт провайдера лишився substrate-рівню. Невідомий tier відсіюється на цьому рівні як помилка контракту.
 
-parseModelId і formatModelSpec утворюють парну нормалізацію між рядковим spec та об’єктом моделі: перша розкладає зовнішній `"provider/model-id"` на складники, друга збирає фактично резолвлену модель назад у той самий формат. Це дозволяє пропускати через модуль як сирі spec-рядки, так і вже вибрані pi-моделі без втрати форми.
+thinkingLevelForTier переводить rung-tier у дискретний рівень thinking, щоб downstream-логіка могла узгоджено трактувати силу моделі без повторного аналізу spec. local-min і local-min-retry зводяться до найнижчого рівня, cloud-min, cloud-avg і cloud-max піднімають рівень відповідно до потужності хмарного вибору.
 
-isLocalModel використовує спільні тири LOCAL_MIN, LOCAL_AVG і LOCAL_MAX як найвищий пріоритет, а для решти spec опирається на провайдера з `N_LLM_LOCAL_PROVIDERS`. Так модуль узгоджує явні локальні політики з ознакою провайдера й дає один бінарний сигнал для ланцюжків, що відрізняють local від cloud.
+parseModelId і formatModelSpec утворюють парний обмін між рядковим model spec та об’єктом моделі: перший розбирає канонічний рядок на provider та id, другий збирає фактично резолвлену модель назад у той самий формат. Якщо spec або модель неповні, результатом є null, щоб не маскувати malformed або відсутній стан.
 
-thinkingLevelForTier не бере участі у резолву моделі, але працює поруч із тирами як окрема проєкція: перетворює rung-рівні на дискретний thinkingLevel для downstream-логіки. Це тримає вибір моделі та рівень міркування синхронними, але розділеними по відповідальності.
+isLocalModel використовує ту саму політику, що й resolveModel: спочатку звіряє явні локальні тири, а потім визначає локальність за provider із model spec. Це дає спільне правило для агрегатів local/cloud і для рішень, де потрібно відрізнити локальний шлях від хмарного без дублювання логіки в consumers.
 
 ## Публічний API
 
@@ -62,6 +58,10 @@ pi-моделі (`session.model`), коли consumer лишив `modelSpec` по
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",
@@ -56,8 +56,8 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@7n/llm-lib-darwin-arm64": "2.9.7",
-    "@7n/llm-lib-linux-x64": "2.9.7"
+    "@7n/llm-lib-darwin-arm64": "2.11.0",
+    "@7n/llm-lib-linux-x64": "2.11.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "~0.80.10",