@kwirthmagnify/kwirth-common-ai 0.5.73 → 0.5.75

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/back.d.ts CHANGED
@@ -5,7 +5,7 @@ interface ILogChannel {
5
5
  logWarning?: (msg: string) => void;
6
6
  logError?: (msg: string) => void;
7
7
  }
8
- import { LanguageModel, ToolSet, generateText as sdkGenerateText } from 'ai';
8
+ import { LanguageModel, ToolSet, generateText as sdkGenerateText, streamText as sdkStreamText } from 'ai';
9
9
  import { z } from 'zod';
10
10
  export declare const buildModel: (llm: ILlm, providers: ILlmProvider[]) => LanguageModel | null;
11
11
  export declare enum EUsageScope {
@@ -73,6 +73,7 @@ export interface IVisionOptions<T> {
73
73
  export declare const generateVision: <T>(opts: IVisionOptions<T>) => Promise<IVisionResult<T>>;
74
74
  export declare const loadModels: (providers: ILlmProvider[], log: ILogChannel) => Promise<void>;
75
75
  export declare const generateText: typeof sdkGenerateText;
76
+ export declare const streamText: typeof sdkStreamText;
76
77
  export { Output, stepCountIs, tool } from 'ai';
77
78
  export type { LanguageModel, ToolSet } from 'ai';
78
79
  export { z } from 'zod';
package/dist/back.js CHANGED
@@ -1,9 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.buildAgentTools = exports.resolveTools = exports.resolveToolRef = exports.invokeToolRef = exports.buildToolHost = exports.listToolsetInfos = exports.listToolsets = exports.getToolset = exports.unregisterToolset = exports.registerToolset = exports.isToolsetGrantedTo = exports.getToolsetGrants = exports.setToolsetGrants = exports.isBuiltInToolsetId = exports.defineTool = exports.runWithToolContext = exports.EToolEffect = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.generateText = exports.loadModels = exports.generateVision = exports.runWithUsageGuard = exports.usageSubjectForKey = exports.getUsageService = exports.setUsageService = exports.setAiLogger = exports.UsageLimitError = exports.EUsageScope = exports.buildModel = void 0;
3
+ exports.buildAgentTools = exports.resolveTools = exports.resolveToolRef = exports.invokeToolRef = exports.buildToolHost = exports.listToolsetInfos = exports.listToolsets = exports.getToolset = exports.unregisterToolset = exports.registerToolset = exports.isToolsetGrantedTo = exports.getToolsetGrants = exports.setToolsetGrants = exports.isBuiltInToolsetId = exports.defineTool = exports.runWithToolContext = exports.EToolEffect = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.streamText = exports.generateText = exports.loadModels = exports.generateVision = exports.runWithUsageGuard = exports.usageSubjectForKey = exports.getUsageService = exports.setUsageService = exports.setAiLogger = exports.UsageLimitError = exports.EUsageScope = exports.buildModel = void 0;
4
4
  const index_1 = require("./index");
5
5
  // Aliased on purpose: the generateText this module EXPORTS is the wrapped one, and nothing below should
6
6
  // be able to reach the raw SDK call by accident — that is exactly how a call would escape the counters.
7
+ // streamText is aliased for the same reason: what leaves here is the counted one.
7
8
  const ai_1 = require("ai");
8
9
  const zod_1 = require("zod");
9
10
  const async_hooks_1 = require("async_hooks");
@@ -177,30 +178,36 @@ const costOf = (origin, tokensIn, tokensOut) => (tokensIn / 1000000) * origin.in
177
178
  offline, and sends something outward on every run. The same seam is what a wrapper around another SDK
178
179
  entry point (streamText) would use.
179
180
  */
180
- const runWithUsageGuard = async (options, call) => {
181
- var _a, _b, _c, _d, _e;
182
- const service = usageService;
183
- const origin = options.model && typeof options.model === 'object' ? modelOrigin.get(options.model) : undefined;
184
- if (!service || !origin)
185
- return await call();
186
- /*
187
- 🔴 The bookkeeping must never be what breaks the feature.
181
+ /*
182
+ 🔴 The bookkeeping must never be what breaks the feature.
188
183
 
189
- Both halves of this used to be plain `await`s on a database, sitting in the critical path of every
190
- AI call. When that database has a bad moment the cost is not a missing counter: it is the whole
191
- call. Measured on 2026-10-14 — `core-ai-usage: Connection Error: Connection ended unexpectedly` one
192
- second in, and then **exactly 120 seconds** until the caller's own timeout gave up. The AI never
193
- got a chance; the two minutes were spent waiting on an accounting read that was never going to
194
- answer, and the user saw a ticket open with no resolution guidance for no reason at all.
184
+ Both halves of this used to be plain `await`s on a database, sitting in the critical path of every
185
+ AI call. When that database has a bad moment the cost is not a missing counter: it is the whole
186
+ call. Measured on 2026-10-14 — `core-ai-usage: Connection Error: Connection ended unexpectedly` one
187
+ second in, and then **exactly 120 seconds** until the caller's own timeout gave up. The AI never
188
+ got a chance; the two minutes were spent waiting on an accounting read that was never going to
189
+ answer, and the user saw a ticket open with no resolution guidance for no reason at all.
195
190
 
196
- So: the read is BOUNDED and FAILS OPEN, and the write does not block the answer.
191
+ So: the read is BOUNDED and FAILS OPEN, and the write does not block the answer.
197
192
 
198
- Failing open is a deliberate trade and it is the uncomfortable one: for the span of a sick usage
199
- database, the ceilings are not enforced. The alternative is worse — an accounting hiccup leaving
200
- every channel in Kwirth without AI. It is said loudly in the log so it cannot pass unnoticed, and
201
- the limits apply again the moment the database answers.
202
- */
203
- const READ_TIMEOUT_MS = 5000;
193
+ Failing open is a deliberate trade and it is the uncomfortable one: for the span of a sick usage
194
+ database, the ceilings are not enforced. The alternative is worse — an accounting hiccup leaving
195
+ every channel in Kwirth without AI. It is said loudly in the log so it cannot pass unnoticed, and
196
+ the limits apply again the moment the database answers.
197
+ */
198
+ const READ_TIMEOUT_MS = 5000;
199
+ /*
200
+ The READ half of the counting: checks the ceilings BEFORE the call. Extracted from runWithUsageGuard
201
+ when streamText needed the same check without the same shape — a stream's caller needs the result
202
+ object immediately, so the guard cannot wrap the whole call (see the streamText wrapper below).
203
+ Bounded and fail-open; throws UsageLimitError when a ceiling is passed.
204
+ */
205
+ const usageGuardCheck = async (options) => {
206
+ var _a;
207
+ const service = usageService;
208
+ const origin = options.model && typeof options.model === 'object' ? modelOrigin.get(options.model) : undefined;
209
+ if (!service || !origin)
210
+ return;
204
211
  let read;
205
212
  const readStarted = Date.now();
206
213
  try {
@@ -229,6 +236,30 @@ const runWithUsageGuard = async (options, call) => {
229
236
  throw new UsageLimitError(exceeded);
230
237
  }
231
238
  }
239
+ };
240
+ /*
241
+ The WRITE half: what a call spent, recorded without blocking the answer. Sin `await`: la respuesta
242
+ ya está. Esperar al apunte solo añade el tiempo de la base a lo que el usuario percibe, y si la base
243
+ está mal, lo añade entero. Lo que se pierde al fallar es un contador; lo que se perdía antes era la
244
+ llamada.
245
+ */
246
+ const usageRecord = (options, result) => {
247
+ var _a, _b, _c, _d;
248
+ const service = usageService;
249
+ const origin = options.model && typeof options.model === 'object' ? modelOrigin.get(options.model) : undefined;
250
+ if (!service || !origin)
251
+ return;
252
+ const tokensIn = (_b = (_a = result.usage) === null || _a === void 0 ? void 0 : _a.inputTokens) !== null && _b !== void 0 ? _b : 0;
253
+ const tokensOut = (_d = (_c = result.usage) === null || _c === void 0 ? void 0 : _c.outputTokens) !== null && _d !== void 0 ? _d : 0;
254
+ void service.add(EUsageScope.LLM_KEY, origin.subject, {
255
+ tokensIn,
256
+ tokensOut,
257
+ calls: 1,
258
+ cost: costOf(origin, tokensIn, tokensOut)
259
+ }).catch(err => logUsage(`AI usage: could not record ${tokensIn + tokensOut} token(s) of a call that DID happen (${err}) — the counters are now short`));
260
+ };
261
+ const runWithUsageGuard = async (options, call) => {
262
+ await usageGuardCheck(options);
232
263
  /* 🔴 En `finally`, no después del `await`. La primera versión medía solo el camino feliz, que es
233
264
  justo el que no hacía falta medir: cuando una llamada se aborta por tiempo —el caso que se estaba
234
265
  investigando— el log no se ejecutaba y seguíamos sin saber si el tiempo era del modelo o de la
@@ -244,19 +275,9 @@ const runWithUsageGuard = async (options, call) => {
244
275
  finally {
245
276
  const callMs = Date.now() - callStarted;
246
277
  if (callMs > 30000 || !ok)
247
- logUsage(`AI usage: the model ${ok ? 'took' : 'FAILED after'} ${Math.round(callMs / 1000)} s (counters read in ${readMs} ms)`);
278
+ logUsage(`AI usage: the model ${ok ? 'took' : 'FAILED after'} ${Math.round(callMs / 1000)} s`);
248
279
  }
249
- const tokensIn = (_c = (_b = result.usage) === null || _b === void 0 ? void 0 : _b.inputTokens) !== null && _c !== void 0 ? _c : 0;
250
- const tokensOut = (_e = (_d = result.usage) === null || _d === void 0 ? void 0 : _d.outputTokens) !== null && _e !== void 0 ? _e : 0;
251
- /* Sin `await`: la respuesta ya está. Esperar al apunte solo añade el tiempo de la base a lo que el
252
- usuario percibe, y si la base está mal, lo añade entero. Lo que se pierde al fallar es un contador;
253
- lo que se perdía antes era la llamada. */
254
- void service.add(EUsageScope.LLM_KEY, origin.subject, {
255
- tokensIn,
256
- tokensOut,
257
- calls: 1,
258
- cost: costOf(origin, tokensIn, tokensOut)
259
- }).catch(err => logUsage(`AI usage: could not record ${tokensIn + tokensOut} token(s) of a call that DID happen (${err}) — the counters are now short`));
280
+ usageRecord(options, result);
260
281
  return result;
261
282
  };
262
283
  exports.runWithUsageGuard = runWithUsageGuard;
@@ -450,6 +471,24 @@ const inferZod = (value) => {
450
471
  restating generateText's generics here and keeping them in step with the SDK by hand.
451
472
  */
452
473
  exports.generateText = ((options) => (0, exports.runWithUsageGuard)(options, () => (0, ai_1.generateText)(options)));
474
+ /*
475
+ 🔴 streamText goes through the same counters as generateText, split in two because of the shape of a
476
+ stream: the ceilings are checked BEFORE the stream starts, and the usage is recorded when the stream
477
+ ends (the SDK reports it with the last chunk). The whole call cannot go through runWithUsageGuard —
478
+ the guard's promise resolves when the call finishes, but the caller needs the result object
479
+ IMMEDIATELY to consume textStream; awaiting the guard would deliver it only after the stream is over.
480
+ A failed stream records nothing, exactly like a failed generateText. First consumer: the vllm channel,
481
+ which re-streams what the model it routed to produces.
482
+ */
483
+ exports.streamText = (async (options) => {
484
+ await usageGuardCheck(options);
485
+ const result = (0, ai_1.streamText)(options);
486
+ // usage is a PromiseLike in the SDK: Promise.resolve gives it the .catch the record path needs.
487
+ void Promise.resolve(result.usage)
488
+ .then(usage => usageRecord(options, { usage }))
489
+ .catch(() => { });
490
+ return result;
491
+ });
453
492
  var ai_2 = require("ai");
454
493
  Object.defineProperty(exports, "Output", { enumerable: true, get: function () { return ai_2.Output; } });
455
494
  Object.defineProperty(exports, "stepCountIs", { enumerable: true, get: function () { return ai_2.stepCountIs; } });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kwirthmagnify/kwirth-common-ai",
3
- "version": "0.5.73",
3
+ "version": "0.5.75",
4
4
  "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
5
5
  "scripts": {
6
6
  "build": "del .\\dist\\* /s /q 2>nul & tsc",
@@ -60,7 +60,7 @@
60
60
  "@kubernetes/client-node": ">=1.0.0"
61
61
  },
62
62
  "devDependencies": {
63
- "@kwirthmagnify/kwirth-common": "^0.5.42",
63
+ "@kwirthmagnify/kwirth-common": "^0.5.76",
64
64
  "@mui/icons-material": "7.1.2",
65
65
  "@mui/material": "7.1.2",
66
66
  "@types/node": "^25.9.1",