@7n/llm-lib 2.10.1 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.10.1",
+  "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",