@7n/llm-lib 2.10.0 → 2.10.1

package/CHANGELOG.md

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

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.10.1",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",