@kwirthmagnify/kwirth-common-ai 0.5.64 → 0.5.66

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
@@ -1,13 +1,54 @@
1
- import { ILlm, ILlmProvider, ECapability, EToolEffect, EToolSensitivity, IAiToolInfo, IAiToolsetInfo, IToolsetConfig } from './index';
1
+ import { ILlm, ILlmProvider, ECapability, EToolEffect, EToolSensitivity, EUsagePeriod, EUsageUnit, IAiToolInfo, IAiToolsetInfo, IToolsetConfig, IUsageAmounts } from './index';
2
2
  import type { AppsV1Api, CoreV1Api, CustomObjectsApi, NetworkingV1Api } from '@kubernetes/client-node';
3
3
  interface ILogChannel {
4
4
  logInfo?: (msg: string) => void;
5
5
  logWarning?: (msg: string) => void;
6
6
  logError?: (msg: string) => void;
7
7
  }
8
- import { LanguageModel, ToolSet } from 'ai';
8
+ import { LanguageModel, ToolSet, generateText as sdkGenerateText } from 'ai';
9
9
  import { z } from 'zod';
10
10
  export declare const buildModel: (llm: ILlm, providers: ILlmProvider[]) => LanguageModel | null;
11
+ export declare enum EUsageScope {
12
+ LLM_KEY = "llmkey",
13
+ CHANNEL = "channel"
14
+ }
15
+ export type { IUsageAmounts, IUsageTotals } from './index';
16
+ export interface IUsageLimitExceeded {
17
+ scope: EUsageScope;
18
+ unit: EUsageUnit;
19
+ period: EUsagePeriod;
20
+ limit: number;
21
+ current: number;
22
+ }
23
+ export interface IUsageService {
24
+ read(scope: EUsageScope, subject: string): Promise<{
25
+ daily: IUsageAmounts;
26
+ monthly: IUsageAmounts;
27
+ }>;
28
+ add(scope: EUsageScope, subject: string, amounts: IUsageAmounts): Promise<void>;
29
+ readonly durable: boolean;
30
+ onCut?(detail: IUsageLimitExceeded): void;
31
+ }
32
+ export declare class UsageLimitError extends Error {
33
+ readonly detail: IUsageLimitExceeded;
34
+ constructor(detail: IUsageLimitExceeded);
35
+ }
36
+ export declare const setUsageService: (service: IUsageService | undefined) => void;
37
+ export declare const getUsageService: () => IUsageService | undefined;
38
+ export declare const usageSubjectForKey: (key: string) => string;
39
+ export declare const runWithUsageGuard: (options: {
40
+ model?: unknown;
41
+ }, call: () => Promise<{
42
+ usage?: {
43
+ inputTokens?: number;
44
+ outputTokens?: number;
45
+ };
46
+ }>) => Promise<{
47
+ usage?: {
48
+ inputTokens?: number;
49
+ outputTokens?: number;
50
+ };
51
+ }>;
11
52
  export interface IVisionResult<T> {
12
53
  object: T | null;
13
54
  text: string;
@@ -29,7 +70,8 @@ export interface IVisionOptions<T> {
29
70
  }
30
71
  export declare const generateVision: <T>(opts: IVisionOptions<T>) => Promise<IVisionResult<T>>;
31
72
  export declare const loadModels: (providers: ILlmProvider[], log: ILogChannel) => Promise<void>;
32
- export { generateText, Output, stepCountIs, tool } from 'ai';
73
+ export declare const generateText: typeof sdkGenerateText;
74
+ export { Output, stepCountIs, tool } from 'ai';
33
75
  export type { LanguageModel, ToolSet } from 'ai';
34
76
  export { z } from 'zod';
35
77
  export declare const zodFromExample: (example: Record<string, unknown>) => z.ZodObject<Record<string, z.ZodTypeAny>>;
package/dist/back.js CHANGED
@@ -1,10 +1,13 @@
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.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.generateText = exports.loadModels = exports.generateVision = exports.runWithUsageGuard = exports.usageSubjectForKey = exports.getUsageService = exports.setUsageService = exports.UsageLimitError = exports.EUsageScope = exports.buildModel = void 0;
4
4
  const index_1 = require("./index");
5
+ // Aliased on purpose: the generateText this module EXPORTS is the wrapped one, and nothing below should
6
+ // be able to reach the raw SDK call by accident — that is exactly how a call would escape the counters.
5
7
  const ai_1 = require("ai");
6
8
  const zod_1 = require("zod");
7
9
  const async_hooks_1 = require("async_hooks");
10
+ const crypto_1 = require("crypto");
8
11
  const openai_1 = require("@ai-sdk/openai");
9
12
  const groq_1 = require("@ai-sdk/groq");
10
13
  const mistral_1 = require("@ai-sdk/mistral");
@@ -13,13 +16,19 @@ const deepseek_1 = require("@ai-sdk/deepseek");
13
16
  const ai_sdk_provider_1 = require("@openrouter/ai-sdk-provider");
14
17
  const anthropic_1 = require("@ai-sdk/anthropic");
15
18
  const buildModel = (llm, providers) => {
16
- var _a, _b, _c;
17
19
  const prov = providers.find(p => p.name === llm.provider);
18
20
  const key = llm.useProviderKey ? prov === null || prov === void 0 ? void 0 : prov.key : llm.key;
19
21
  if (!key) {
20
22
  console.log('Could not find a key');
21
23
  return null;
22
24
  }
25
+ // Whatever the switch returns is annotated with what it was built from, so generateText knows which
26
+ // budget to count it against. Wrapping here and not at each 'return' keeps the two in step.
27
+ return rememberOrigin(buildSdkModel(llm, prov, key), llm, prov, key);
28
+ };
29
+ exports.buildModel = buildModel;
30
+ const buildSdkModel = (llm, prov, key) => {
31
+ var _a, _b, _c;
23
32
  const type = (_b = (_a = prov === null || prov === void 0 ? void 0 : prov.type) !== null && _a !== void 0 ? _a : prov === null || prov === void 0 ? void 0 : prov.name) !== null && _b !== void 0 ? _b : llm.provider;
24
33
  switch (type) {
25
34
  case 'openai': return (0, openai_1.createOpenAI)({ apiKey: key })(llm.model);
@@ -41,7 +50,145 @@ const buildModel = (llm, providers) => {
41
50
  return null;
42
51
  }
43
52
  };
44
- exports.buildModel = buildModel;
53
+ // ─────────────────────────────────────────────────────────────────────────────────────────────────────
54
+ // Usage control (plan: plans/ai-usage-control/PLAN.md, S1)
55
+ //
56
+ // Every LLM call in Kwirth goes through the generateText below. Not by convention: the plugins map
57
+ // '@kwirthmagnify/kwirth-common-ai' to global.__kwirth_back__ in their build, so what they execute is the
58
+ // CORE's copy of this module. Counting here counts everything, and nothing in a plugin has to change.
59
+ //
60
+ // What this file does NOT do is store anything: the counters need SQL, and dragging that into common-ai
61
+ // would put a database client inside the contract every extension imports. The core implements
62
+ // IUsageService and registers it; without one, nothing is counted and nothing is cut.
63
+ // ─────────────────────────────────────────────────────────────────────────────────────────────────────
64
+ /* Which of the two axes a limit belongs to. */
65
+ var EUsageScope;
66
+ (function (EUsageScope) {
67
+ EUsageScope["LLM_KEY"] = "llmkey";
68
+ EUsageScope["CHANNEL"] = "channel";
69
+ })(EUsageScope || (exports.EUsageScope = EUsageScope = {}));
70
+ /*
71
+ Thrown instead of calling the model. A subclass and not a plain Error because a channel has to be able
72
+ to tell 'you have no quota left' from 'the model answered badly', and a string message cannot be
73
+ inspected without parsing it.
74
+ */
75
+ class UsageLimitError extends Error {
76
+ constructor(detail) {
77
+ super(`AI usage limit reached: ${detail.unit} ${detail.period} on ${detail.scope} (${detail.current} of ${detail.limit})`);
78
+ this.name = 'UsageLimitError';
79
+ this.detail = detail;
80
+ }
81
+ }
82
+ exports.UsageLimitError = UsageLimitError;
83
+ let usageService;
84
+ /* The core calls this at startup. Without it everything below is a no-op and the LLM is reached as ever. */
85
+ const setUsageService = (service) => { usageService = service; };
86
+ exports.setUsageService = setUsageService;
87
+ const getUsageService = () => usageService;
88
+ exports.getUsageService = getUsageService;
89
+ const modelOrigin = new WeakMap();
90
+ /*
91
+ The subject of the llmkey axis is a HASH of the effective key, never the key. Two LLM entries on the
92
+ same key land on the same subject and share one budget, which is what the provider does when it bills
93
+ it. And the counters table ends up holding no secret.
94
+ */
95
+ const keyFingerprint = (key) => (0, crypto_1.createHash)('sha256').update(key).digest('hex').slice(0, 32);
96
+ /*
97
+ The same subject the counters are written under, for whoever needs to READ them back — the core, to
98
+ show an admin what a provider or a model has spent. Exported so that is computed in one place: a
99
+ second implementation of this hash would show consumption that silently belongs to nobody.
100
+ */
101
+ const usageSubjectForKey = (key) => keyFingerprint(key);
102
+ exports.usageSubjectForKey = usageSubjectForKey;
103
+ /*
104
+ Records what a model was built from, so generateText can count against it. Called by buildModel; a
105
+ model built any other way simply has no origin and is not counted — never silently miscounted.
106
+ */
107
+ const rememberOrigin = (model, llm, prov, key) => {
108
+ var _a, _b;
109
+ if (model && typeof model === 'object') {
110
+ modelOrigin.set(model, {
111
+ subject: keyFingerprint(key),
112
+ limits: llm.useProviderKey ? prov === null || prov === void 0 ? void 0 : prov.limits : llm.limits,
113
+ inputCostPerMillion: (_a = llm.inputCostPerMillion) !== null && _a !== void 0 ? _a : 0,
114
+ outputCostPerMillion: (_b = llm.outputCostPerMillion) !== null && _b !== void 0 ? _b : 0
115
+ });
116
+ }
117
+ return model;
118
+ };
119
+ /* The four units, paired with where each one is read from in a counted total. */
120
+ const UNITS = [
121
+ { unit: index_1.EUsageUnit.TOKENS_IN, of: a => a.tokensIn },
122
+ { unit: index_1.EUsageUnit.TOKENS_OUT, of: a => a.tokensOut },
123
+ { unit: index_1.EUsageUnit.CALLS, of: a => a.calls },
124
+ { unit: index_1.EUsageUnit.COST, of: a => a.cost }
125
+ ];
126
+ const windowsOf = (limits, unit) => limits === null || limits === void 0 ? void 0 : limits[unit];
127
+ /*
128
+ The ONE rule: the call goes out only if NO active ceiling is exceeded. Whichever is passed first —
129
+ whatever axis, whatever unit, whatever window — cuts, and what is returned says which, so the error
130
+ can name it instead of talking about 'a limit'.
131
+
132
+ 'Exceeded' is >=, not >: a ceiling of 100 calls means the hundred-and-first does not happen, so the
133
+ check at 100 already has to cut.
134
+ */
135
+ const findExceeded = (scope, limits, daily, monthly) => {
136
+ if (!limits)
137
+ return undefined;
138
+ for (const { unit, of } of UNITS) {
139
+ const w = windowsOf(limits, unit);
140
+ if (!(w === null || w === void 0 ? void 0 : w.enabled))
141
+ continue;
142
+ if (w.daily !== undefined && of(daily) >= w.daily)
143
+ return { scope, unit, period: index_1.EUsagePeriod.DAY, limit: w.daily, current: of(daily) };
144
+ if (w.monthly !== undefined && of(monthly) >= w.monthly)
145
+ return { scope, unit, period: index_1.EUsagePeriod.MONTH, limit: w.monthly, current: of(monthly) };
146
+ }
147
+ return undefined;
148
+ };
149
+ /* What a response cost, in money, with the price of the LLM that was actually used. */
150
+ const costOf = (origin, tokensIn, tokensOut) => (tokensIn / 1000000) * origin.inputCostPerMillion + (tokensOut / 1000000) * origin.outputCostPerMillion;
151
+ /*
152
+ The LLM call every channel in Kwirth makes, with the counters around it.
153
+
154
+ 🔴 The order is not arbitrary. The ceilings are checked BEFORE calling, with what has been spent so
155
+ far; the usage is added AFTER, because the SDK reports it with the answer and not before. So a limit
156
+ on CALLS stops the call that would exceed it, and a limit on TOKENS or COST stops the NEXT one: the
157
+ one that crosses the line has already been paid for. That is the protocol, not a shortcut, and the UI
158
+ says so where the limit is set.
159
+
160
+ A model nobody built with buildModel has no origin, so it is not counted. Not counting is a visible
161
+ gap; counting it against someone else's budget would be a lie.
162
+
163
+ It takes the call as a parameter rather than making it, which is what lets the accounting half be
164
+ exercised without reaching a real provider — a harness that calls api.openai.com is slow, fails
165
+ offline, and sends something outward on every run. The same seam is what a wrapper around another SDK
166
+ entry point (streamText) would use.
167
+ */
168
+ const runWithUsageGuard = async (options, call) => {
169
+ var _a, _b, _c, _d, _e;
170
+ const service = usageService;
171
+ const origin = options.model && typeof options.model === 'object' ? modelOrigin.get(options.model) : undefined;
172
+ if (!service || !origin)
173
+ return await call();
174
+ const { daily, monthly } = await service.read(EUsageScope.LLM_KEY, origin.subject);
175
+ const exceeded = findExceeded(EUsageScope.LLM_KEY, origin.limits, daily, monthly);
176
+ if (exceeded) {
177
+ (_a = service.onCut) === null || _a === void 0 ? void 0 : _a.call(service, exceeded);
178
+ throw new UsageLimitError(exceeded);
179
+ }
180
+ const result = await call();
181
+ const tokensIn = (_c = (_b = result.usage) === null || _b === void 0 ? void 0 : _b.inputTokens) !== null && _c !== void 0 ? _c : 0;
182
+ const tokensOut = (_e = (_d = result.usage) === null || _d === void 0 ? void 0 : _d.outputTokens) !== null && _e !== void 0 ? _e : 0;
183
+ await service.add(EUsageScope.LLM_KEY, origin.subject, {
184
+ tokensIn,
185
+ tokensOut,
186
+ calls: 1,
187
+ cost: costOf(origin, tokensIn, tokensOut)
188
+ });
189
+ return result;
190
+ };
191
+ exports.runWithUsageGuard = runWithUsageGuard;
45
192
  // Generic MULTIMODAL call: sends an image plus a prompt to an LLM and returns STRUCTURED output validated by
46
193
  // a Zod schema (the Output.object pattern). Reusable across the whole platform (Iter uses it to extract a map
47
194
  // from a diagram). It never throws: errors come back in `error`.
@@ -57,7 +204,7 @@ const generateVision = async (opts) => {
57
204
  mediaType: opts.mediaType, imageBytes: ((_l = opts.image) !== null && _l !== void 0 ? _l : '').length,
58
205
  systemLen: ((_m = opts.system) !== null && _m !== void 0 ? _m : '').length, providerOptions: opts.providerOptions,
59
206
  });
60
- const { output, text, usage } = await (0, ai_1.generateText)(Object.assign({ model: opts.model, temperature: (_o = opts.temperature) !== null && _o !== void 0 ? _o : 0, system: opts.system, messages: [{
207
+ const { output, text, usage } = await (0, exports.generateText)(Object.assign({ model: opts.model, temperature: (_o = opts.temperature) !== null && _o !== void 0 ? _o : 0, system: opts.system, messages: [{
61
208
  role: 'user',
62
209
  content: [{ type: 'text', text: opts.prompt }, imagePart],
63
210
  }], output: ai_1.Output.object({ schema: opts.schema }) }, (opts.providerOptions ? { providerOptions: opts.providerOptions } : {})));
@@ -223,8 +370,16 @@ const inferZod = (value) => {
223
370
  // Re-export AI SDK symbols so plugins can use them without bundling the SDK
224
371
  // The TYPES needed by anyone writing a helper around generateText are re-exported too: without
225
372
  // LanguageModel and ToolSet a plugin cannot type its own functions and ends up with 'any'.
373
+ /*
374
+ 🔴 generateText is NOT re-exported from the SDK any more: what leaves here is the wrapped one, which
375
+ is what makes every LLM call in Kwirth countable. Re-exporting the raw one again would open the hole
376
+ this whole feature exists to close, and nothing would fail to compile to warn you.
377
+
378
+ The cast is to the SDK's own type because the wrapper has exactly that signature: the alternative is
379
+ restating generateText's generics here and keeping them in step with the SDK by hand.
380
+ */
381
+ exports.generateText = ((options) => (0, exports.runWithUsageGuard)(options, () => (0, ai_1.generateText)(options)));
226
382
  var ai_2 = require("ai");
227
- Object.defineProperty(exports, "generateText", { enumerable: true, get: function () { return ai_2.generateText; } });
228
383
  Object.defineProperty(exports, "Output", { enumerable: true, get: function () { return ai_2.Output; } });
229
384
  Object.defineProperty(exports, "stepCountIs", { enumerable: true, get: function () { return ai_2.stepCountIs; } });
230
385
  Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return ai_2.tool; } });
package/dist/front.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import React from 'react';
2
- import { ILlm, ILlmModel, ILlmProvider } from './index';
2
+ import { ILlm, ILlmModel, ILlmProvider, IUsageTotals } from './index';
3
3
  interface ILlmSelectorProps {
4
4
  llms: ILlm[];
5
5
  value: string;
@@ -13,6 +13,8 @@ interface IAiConfigLlmProps {
13
13
  onClose: (llms: ILlm[] | undefined) => void;
14
14
  providers: ILlmProvider[];
15
15
  llms: ILlm[];
16
+ usage?: Record<string, IUsageTotals>;
17
+ usageDurable?: boolean;
16
18
  }
17
19
  declare const AiConfigLlm: React.FC<IAiConfigLlmProps>;
18
20
  interface IAiConfigProviderProps {
@@ -20,6 +22,8 @@ interface IAiConfigProviderProps {
20
22
  providers: ILlmProvider[];
21
23
  onClose: (providers: ILlmProvider[] | undefined) => void;
22
24
  onLoadModels?: (provider: ILlmProvider) => Promise<ILlmModel[]>;
25
+ usage?: Record<string, IUsageTotals>;
26
+ usageDurable?: boolean;
23
27
  }
24
28
  declare const AiConfigProvider: React.FC<IAiConfigProviderProps>;
25
29
  interface IToolSelectorProps {
package/dist/front.js CHANGED
@@ -69,6 +69,66 @@ const downloadJson = async (data, filename) => {
69
69
  a.click();
70
70
  URL.revokeObjectURL(url);
71
71
  };
72
+ const index_1 = require("./index");
73
+ /* The four units in the order an admin thinks about them: what it costs, how often, how much it moved. */
74
+ const USAGE_ROWS = [
75
+ { unit: index_1.EUsageUnit.COST, label: 'Cost (€/$)', of: a => a.cost },
76
+ { unit: index_1.EUsageUnit.CALLS, label: 'Calls', of: a => a.calls },
77
+ { unit: index_1.EUsageUnit.TOKENS_IN, label: 'Input tokens', of: a => a.tokensIn },
78
+ { unit: index_1.EUsageUnit.TOKENS_OUT, label: 'Output tokens', of: a => a.tokensOut }
79
+ ];
80
+ /* 1234.5 → '1,235' and 0.42 → '0.42': a cost needs its decimals, a token count is noise with them. */
81
+ const formatSpent = (value) => value >= 100 ? Math.round(value).toLocaleString() : String(Math.round(value * 100) / 100);
82
+ /*
83
+ The ceilings of one subject — a provider key or a model's own key. Shared by both dialogs because the
84
+ rule is the same in both, and two copies of it would drift.
85
+
86
+ Each unit carries its own switch, apart from its numbers: turning a limit off for a week should not
87
+ cost the admin the numbers he had worked out.
88
+ */
89
+ const UsageLimitsEditor = (props) => {
90
+ var _a;
91
+ const limits = (_a = props.value) !== null && _a !== void 0 ? _a : {};
92
+ const patch = (unit, change) => {
93
+ var _a;
94
+ const current = (_a = limits[unit]) !== null && _a !== void 0 ? _a : { enabled: false };
95
+ props.onChange(Object.assign(Object.assign({}, limits), { [unit]: Object.assign(Object.assign({}, current), change) }));
96
+ };
97
+ const numberOrUndefined = (text) => text === '' ? undefined : +text;
98
+ return (react_1.default.createElement(material_1.Stack, { direction: 'column', spacing: 1, sx: { mt: 1 } },
99
+ react_1.default.createElement(material_1.Typography, { variant: 'body2', color: 'text.secondary' },
100
+ "Stop spending on ",
101
+ react_1.default.createElement("b", null, props.subject),
102
+ ". A call goes out only if ",
103
+ react_1.default.createElement("b", null, "no"),
104
+ " enabled ceiling is reached \u2014 whichever is passed first blocks it, and the channel is told why."),
105
+ react_1.default.createElement(material_1.Typography, { variant: 'caption', color: 'text.secondary' },
106
+ "\u26A0\uFE0F A ",
107
+ react_1.default.createElement("b", null, "calls"),
108
+ " ceiling stops the call that would exceed it. ",
109
+ react_1.default.createElement("b", null, "Tokens"),
110
+ " and ",
111
+ react_1.default.createElement("b", null, "cost"),
112
+ " are only known once the model has answered, so those stop the ",
113
+ react_1.default.createElement("b", null, "next"),
114
+ " call: the one that crosses the line has already been paid for."),
115
+ props.usage && props.durable === false &&
116
+ react_1.default.createElement(material_1.Typography, { variant: 'caption', color: 'warning.main' },
117
+ "\u26A0\uFE0F These counters are kept ",
118
+ react_1.default.createElement("b", null, "in memory"),
119
+ ", because this Kwirth has no SQL configured: they go back to zero on every restart, and so do the limits that depend on them."),
120
+ USAGE_ROWS.map(({ unit, label, of }) => {
121
+ var _a, _b, _c, _d, _e;
122
+ const w = (_a = limits[unit]) !== null && _a !== void 0 ? _a : { enabled: false };
123
+ // What has been spent goes in the helper text of its own window: next to the number it is
124
+ // measured against, which is the only place it answers anything.
125
+ const spent = (amounts) => amounts ? `${formatSpent(of(amounts))} so far` : undefined;
126
+ return (react_1.default.createElement(material_1.Stack, { key: unit, direction: 'row', spacing: 1, alignItems: 'flex-start' },
127
+ react_1.default.createElement(material_1.FormControlLabel, { sx: { width: '190px', mr: 0, mt: 1 }, control: react_1.default.createElement(material_1.Checkbox, { checked: !!w.enabled, disabled: props.disabled, onChange: e => patch(unit, { enabled: e.target.checked }) }), label: label }),
128
+ react_1.default.createElement(material_1.TextField, { value: (_b = w.daily) !== null && _b !== void 0 ? _b : '', onChange: e => patch(unit, { daily: numberOrUndefined(e.target.value) }), label: 'Per day', variant: 'standard', type: 'number', fullWidth: true, disabled: props.disabled || !w.enabled, inputProps: { min: 0 }, placeholder: 'no limit', helperText: spent((_c = props.usage) === null || _c === void 0 ? void 0 : _c.daily) }),
129
+ react_1.default.createElement(material_1.TextField, { value: (_d = w.monthly) !== null && _d !== void 0 ? _d : '', onChange: e => patch(unit, { monthly: numberOrUndefined(e.target.value) }), label: 'Per month', variant: 'standard', type: 'number', fullWidth: true, disabled: props.disabled || !w.enabled, inputProps: { min: 0 }, placeholder: 'no limit', helperText: spent((_e = props.usage) === null || _e === void 0 ? void 0 : _e.monthly) })));
130
+ })));
131
+ };
72
132
  const LlmSelector = ({ llms, value, onChange, label = 'LLM', size = 'small', fullWidth = true }) => {
73
133
  return (react_1.default.createElement(material_1.FormControl, { size: size, fullWidth: fullWidth },
74
134
  react_1.default.createElement(material_1.InputLabel, null, label),
@@ -82,7 +142,7 @@ const LlmSelector = ({ llms, value, onChange, label = 'LLM', size = 'small', ful
82
142
  };
83
143
  exports.LlmSelector = LlmSelector;
84
144
  const AiConfigLlm = (props) => {
85
- var _a, _b;
145
+ var _a, _b, _c;
86
146
  const [llms, setLlms] = (0, react_1.useState)(JSON.parse(JSON.stringify(props.llms)));
87
147
  const importLlmRef = (0, react_1.useRef)(null);
88
148
  const [selectedIndex, setSelectedIndex] = (0, react_1.useState)(null);
@@ -93,6 +153,7 @@ const AiConfigLlm = (props) => {
93
153
  const [temperature, setTemperature] = (0, react_1.useState)(0);
94
154
  const [useProviderKey, setUseProviderKey] = (0, react_1.useState)(true);
95
155
  const [key, setKey] = (0, react_1.useState)('');
156
+ const [limits, setLimits] = (0, react_1.useState)({});
96
157
  const [inputCostPerMillion, setInputCostPerMillion] = (0, react_1.useState)(0);
97
158
  const [outputCostPerMillion, setOutputCostPerMillion] = (0, react_1.useState)(0);
98
159
  // Re-syncs state when the models arrive asynchronously (same race fix as AiConfigProvider): on open,
@@ -103,7 +164,7 @@ const AiConfigLlm = (props) => {
103
164
  setSelectedIndex(null);
104
165
  }, [props.llms]);
105
166
  const onLlmSelected = (index) => {
106
- var _a, _b;
167
+ var _a, _b, _c;
107
168
  const l = llms[index];
108
169
  if (l) {
109
170
  setId(l.id);
@@ -114,6 +175,7 @@ const AiConfigLlm = (props) => {
114
175
  setKey(l.key);
115
176
  setInputCostPerMillion((_a = l.inputCostPerMillion) !== null && _a !== void 0 ? _a : 0);
116
177
  setOutputCostPerMillion((_b = l.outputCostPerMillion) !== null && _b !== void 0 ? _b : 0);
178
+ setLimits((_c = l.limits) !== null && _c !== void 0 ? _c : {});
117
179
  setSelectedIndex(index);
118
180
  }
119
181
  };
@@ -127,9 +189,12 @@ const AiConfigLlm = (props) => {
127
189
  setKey('');
128
190
  setInputCostPerMillion(0);
129
191
  setOutputCostPerMillion(0);
192
+ setLimits({});
130
193
  };
131
194
  const onAdd = () => {
132
- const llm = { id, provider, model, temperature, useProviderKey, key, inputCostPerMillion: inputCostPerMillion === '' ? 0 : inputCostPerMillion, outputCostPerMillion: outputCostPerMillion === '' ? 0 : outputCostPerMillion };
195
+ // Limits only travel with a model that has its OWN key: with a borrowed one the budget is the
196
+ // provider's, and keeping a stale copy here would show a ceiling that nothing enforces.
197
+ const llm = Object.assign({ id, provider, model, temperature, useProviderKey, key, inputCostPerMillion: inputCostPerMillion === '' ? 0 : inputCostPerMillion, outputCostPerMillion: outputCostPerMillion === '' ? 0 : outputCostPerMillion }, (useProviderKey ? {} : { limits }));
133
198
  const updated = [...llms];
134
199
  if (selectedIndex !== null)
135
200
  updated[selectedIndex] = llm;
@@ -178,7 +243,10 @@ const AiConfigLlm = (props) => {
178
243
  react_1.default.createElement(material_1.TextField, { value: key, onChange: e => setKey(e.target.value), disabled: useProviderKey, label: 'API Key', placeholder: 'Enter API Key', variant: 'standard', fullWidth: true, type: showPassword ? 'text' : 'password', InputProps: {
179
244
  endAdornment: (react_1.default.createElement(material_1.InputAdornment, { position: 'end' },
180
245
  react_1.default.createElement(material_1.IconButton, { onClick: () => setShowPassword(!showPassword), edge: 'end' }, showPassword ? react_1.default.createElement(VisibilityOff_1.default, null) : react_1.default.createElement(Visibility_1.default, null))))
181
- } })),
246
+ } }),
247
+ useProviderKey
248
+ ? react_1.default.createElement(material_1.Typography, { variant: 'caption', color: 'text.secondary' }, "Usage limits for this model live on its provider, because it borrows the provider's key \u2014 and that key is what gets billed.")
249
+ : react_1.default.createElement(UsageLimitsEditor, { value: limits, onChange: setLimits, subject: `this model's own key`, usage: (_c = props.usage) === null || _c === void 0 ? void 0 : _c[id], durable: props.usageDurable })),
182
250
  react_1.default.createElement(material_1.Stack, { direction: 'row', spacing: 1 },
183
251
  react_1.default.createElement(material_1.Button, { variant: 'outlined', size: 'small', onClick: onNew }, "New"),
184
252
  react_1.default.createElement(material_1.Typography, { flex: 1 }),
@@ -206,7 +274,7 @@ const AiConfigLlm = (props) => {
206
274
  };
207
275
  exports.AiConfigLlm = AiConfigLlm;
208
276
  const AiConfigProvider = (props) => {
209
- var _a;
277
+ var _a, _b;
210
278
  const [providers, setProviders] = (0, react_1.useState)(JSON.parse(JSON.stringify(props.providers)));
211
279
  const importProvRef = (0, react_1.useRef)(null);
212
280
  const [selectedIndex, setSelectedIndex] = (0, react_1.useState)(null);
@@ -221,15 +289,17 @@ const AiConfigProvider = (props) => {
221
289
  const [providerType, setProviderType] = (0, react_1.useState)((_a = props.providersAvailable[0]) !== null && _a !== void 0 ? _a : '');
222
290
  const [providerKey, setProviderKey] = (0, react_1.useState)('');
223
291
  const [providerEndpoint, setProviderEndpoint] = (0, react_1.useState)('');
292
+ const [providerLimits, setProviderLimits] = (0, react_1.useState)({});
224
293
  const [pendingModels, setPendingModels] = (0, react_1.useState)([]); // solo para mostrar count en el botón
225
294
  const onProviderSelected = (p, index) => {
226
- var _a, _b, _c, _d;
295
+ var _a, _b, _c, _d, _e;
227
296
  setProviderName(p.name);
228
297
  setProviderType((_a = p.type) !== null && _a !== void 0 ? _a : p.name);
229
298
  setProviderKey(p.key);
230
299
  setProviderEndpoint((_b = p.endpoint) !== null && _b !== void 0 ? _b : '');
231
- loadedModelsRef.current = (_c = p.models) !== null && _c !== void 0 ? _c : [];
232
- setPendingModels((_d = p.models) !== null && _d !== void 0 ? _d : []);
300
+ setProviderLimits((_c = p.limits) !== null && _c !== void 0 ? _c : {});
301
+ loadedModelsRef.current = (_d = p.models) !== null && _d !== void 0 ? _d : [];
302
+ setPendingModels((_e = p.models) !== null && _e !== void 0 ? _e : []);
233
303
  setSelectedIndex(index);
234
304
  };
235
305
  const onNew = () => {
@@ -239,6 +309,7 @@ const AiConfigProvider = (props) => {
239
309
  setProviderType((_a = props.providersAvailable[0]) !== null && _a !== void 0 ? _a : '');
240
310
  setProviderKey('');
241
311
  setProviderEndpoint('');
312
+ setProviderLimits({});
242
313
  loadedModelsRef.current = [];
243
314
  setPendingModels([]);
244
315
  };
@@ -249,9 +320,9 @@ const AiConfigProvider = (props) => {
249
320
  const models = loadedModelsRef.current;
250
321
  const updated = [...providers];
251
322
  if (selectedIndex !== null)
252
- updated[selectedIndex] = Object.assign(Object.assign({}, updated[selectedIndex]), { name: providerName, type: providerType, key: providerKey, models, endpoint });
323
+ updated[selectedIndex] = Object.assign(Object.assign({}, updated[selectedIndex]), { name: providerName, type: providerType, key: providerKey, models, endpoint, limits: providerLimits });
253
324
  else
254
- updated.push({ name: providerName, type: providerType, key: providerKey, models, endpoint });
325
+ updated.push({ name: providerName, type: providerType, key: providerKey, models, endpoint, limits: providerLimits });
255
326
  setProviders(updated);
256
327
  onNew();
257
328
  };
@@ -306,6 +377,7 @@ const AiConfigProvider = (props) => {
306
377
  react_1.default.createElement(material_1.IconButton, { onClick: () => setShowPassword(!showPassword), edge: 'end' }, showPassword ? react_1.default.createElement(VisibilityOff_1.default, null) : react_1.default.createElement(Visibility_1.default, null))))
307
378
  } }),
308
379
  providerType === 'openai-compat' && (react_1.default.createElement(material_1.TextField, { label: 'Base URL', variant: 'standard', fullWidth: true, placeholder: 'https://your-maas-host/v1', value: providerEndpoint, onChange: e => setProviderEndpoint(e.target.value), helperText: 'OpenAI-compatible API base URL (e.g. Huawei MaaS, vLLM, LM Studio\u2026)' })),
380
+ react_1.default.createElement(UsageLimitsEditor, { value: providerLimits, onChange: setProviderLimits, subject: `this provider's key`, disabled: !providerName.trim(), usage: (_b = props.usage) === null || _b === void 0 ? void 0 : _b[providerName], durable: props.usageDurable }),
309
381
  react_1.default.createElement(material_1.Box, { sx: { flexGrow: 1 } }),
310
382
  react_1.default.createElement(material_1.Stack, { direction: 'row', spacing: 1, alignItems: 'center' },
311
383
  react_1.default.createElement(material_1.Button, { variant: 'outlined', onClick: onNew }, "New"),
package/dist/index.d.ts CHANGED
@@ -7,12 +7,44 @@ export interface ILlmModel {
7
7
  description: string;
8
8
  type: 'text' | 'image' | 'video' | 'other';
9
9
  }
10
+ export declare enum EUsageUnit {
11
+ TOKENS_IN = "tokensIn",
12
+ TOKENS_OUT = "tokensOut",
13
+ CALLS = "calls",
14
+ COST = "cost"
15
+ }
16
+ export declare enum EUsagePeriod {
17
+ DAY = "day",
18
+ MONTH = "month"
19
+ }
20
+ export interface IUsageWindows {
21
+ enabled: boolean;
22
+ daily?: number;
23
+ monthly?: number;
24
+ }
25
+ export interface IUsageLimits {
26
+ tokensIn?: IUsageWindows;
27
+ tokensOut?: IUsageWindows;
28
+ calls?: IUsageWindows;
29
+ cost?: IUsageWindows;
30
+ }
31
+ export interface IUsageAmounts {
32
+ tokensIn: number;
33
+ tokensOut: number;
34
+ calls: number;
35
+ cost: number;
36
+ }
37
+ export interface IUsageTotals {
38
+ daily: IUsageAmounts;
39
+ monthly: IUsageAmounts;
40
+ }
10
41
  export interface ILlmProvider {
11
42
  name: string;
12
43
  type: string;
13
44
  key: string;
14
45
  models: ILlmModel[];
15
46
  endpoint?: string;
47
+ limits?: IUsageLimits;
16
48
  }
17
49
  export interface ILlm {
18
50
  id: string;
@@ -23,6 +55,7 @@ export interface ILlm {
23
55
  key: string;
24
56
  inputCostPerMillion?: number;
25
57
  outputCostPerMillion?: number;
58
+ limits?: IUsageLimits;
26
59
  data?: unknown;
27
60
  }
28
61
  export declare const STORAGE_KEY_AGENTS = "kwirth-ai-agents";
package/dist/index.js CHANGED
@@ -1,9 +1,24 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.parseToolRef = exports.toolRef = exports.TOOL_REF_SEPARATOR = exports.ECapability = exports.EToolSensitivity = exports.EToolEffect = exports.STORAGE_KEY_AGENTS = exports.PROVIDERS_AVAILABLE = exports.STORAGE_KEY_LLMS = exports.STORAGE_KEY_PROVIDERS = void 0;
3
+ exports.parseToolRef = exports.toolRef = exports.TOOL_REF_SEPARATOR = exports.ECapability = exports.EToolSensitivity = exports.EToolEffect = exports.STORAGE_KEY_AGENTS = exports.EUsagePeriod = exports.EUsageUnit = exports.PROVIDERS_AVAILABLE = exports.STORAGE_KEY_LLMS = exports.STORAGE_KEY_PROVIDERS = void 0;
4
4
  exports.STORAGE_KEY_PROVIDERS = 'kwirth-ai-providers';
5
5
  exports.STORAGE_KEY_LLMS = 'kwirth-ai-llms';
6
6
  exports.PROVIDERS_AVAILABLE = ['google', 'openai', 'openrouter', 'mistral', 'groq', 'deepseek', 'anthropic', 'openai-compat'];
7
+ /* What a usage limit is counted in. */
8
+ var EUsageUnit;
9
+ (function (EUsageUnit) {
10
+ EUsageUnit["TOKENS_IN"] = "tokensIn";
11
+ EUsageUnit["TOKENS_OUT"] = "tokensOut";
12
+ EUsageUnit["CALLS"] = "calls";
13
+ /* Money, from the per-million prices the admin already sets on each LLM. */
14
+ EUsageUnit["COST"] = "cost";
15
+ })(EUsageUnit || (exports.EUsageUnit = EUsageUnit = {}));
16
+ /* The window a limit is measured over. Both can be set at once, each with its own ceiling. */
17
+ var EUsagePeriod;
18
+ (function (EUsagePeriod) {
19
+ EUsagePeriod["DAY"] = "day";
20
+ EUsagePeriod["MONTH"] = "month";
21
+ })(EUsagePeriod || (exports.EUsagePeriod = EUsagePeriod = {}));
7
22
  exports.STORAGE_KEY_AGENTS = 'kwirth-ai-agents';
8
23
  // ─────────────────────────────────────────────────────────────────────────────────────────────────────
9
24
  // AI toolset contract (plan: plans/ai-tools/PLAN.md, S1)
package/package.json CHANGED
@@ -1,79 +1,79 @@
1
- {
2
- "name": "@kwirthmagnify/kwirth-common-ai",
3
- "version": "0.5.64",
4
- "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
5
- "scripts": {
6
- "build": "del .\\dist\\* /s /q 2>nul & tsc",
7
- "test": "node --test tests/*.test.mjs"
8
- },
9
- "publishConfig": {
10
- "access": "public"
11
- },
12
- "main": "dist/index.js",
13
- "module": "dist/index.js",
14
- "types": "dist/index.d.ts",
15
- "exports": {
16
- ".": {
17
- "types": "./dist/index.d.ts",
18
- "require": "./dist/index.js",
19
- "default": "./dist/index.js"
20
- },
21
- "./back": {
22
- "types": "./dist/back.d.ts",
23
- "require": "./dist/back.js",
24
- "default": "./dist/back.js"
25
- },
26
- "./front": {
27
- "types": "./dist/front.d.ts",
28
- "require": "./dist/front.js",
29
- "default": "./dist/front.js"
30
- }
31
- },
32
- "typesVersions": {
33
- "*": {
34
- "back": [
35
- "dist/back.d.ts"
36
- ],
37
- "front": [
38
- "dist/front.d.ts"
39
- ]
40
- }
41
- },
42
- "files": [
43
- "dist"
44
- ],
45
- "author": "Julio Fernandez",
46
- "license": "ISC",
47
- "dependencies": {
48
- "@ai-sdk/anthropic": "^3.0.116",
49
- "@ai-sdk/deepseek": "^2.0.29",
50
- "@ai-sdk/google": "^3.0.64",
51
- "@ai-sdk/groq": "^3.0.35",
52
- "@ai-sdk/mistral": "^3.0.30",
53
- "@ai-sdk/openai": "^3.0.53",
54
- "@openrouter/ai-sdk-provider": "^2.8.0",
55
- "ai": "^6.0.174",
56
- "zod": "^4.3.6"
57
- },
58
- "peerDependencies": {
59
- "react": ">=18.0.0",
60
- "@kubernetes/client-node": ">=1.0.0"
61
- },
62
- "devDependencies": {
63
- "@kwirthmagnify/kwirth-common": "^0.5.42",
64
- "@mui/icons-material": "7.1.2",
65
- "@mui/material": "7.1.2",
66
- "@types/node": "^25.9.1",
67
- "@types/react": "^18.3.0",
68
- "typescript": "^5.4.0",
69
- "@kubernetes/client-node": "^1.4.0"
70
- },
71
- "peerDependenciesMeta": {
72
- "@kubernetes/client-node": {
73
- "optional": true
74
- },
75
- "react": {
76
- "optional": true
77
- }
78
- }
79
- }
1
+ {
2
+ "name": "@kwirthmagnify/kwirth-common-ai",
3
+ "version": "0.5.66",
4
+ "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
5
+ "scripts": {
6
+ "build": "del .\\dist\\* /s /q 2>nul & tsc",
7
+ "test": "node --test tests/*.test.mjs"
8
+ },
9
+ "publishConfig": {
10
+ "access": "public"
11
+ },
12
+ "main": "dist/index.js",
13
+ "module": "dist/index.js",
14
+ "types": "dist/index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/index.d.ts",
18
+ "require": "./dist/index.js",
19
+ "default": "./dist/index.js"
20
+ },
21
+ "./back": {
22
+ "types": "./dist/back.d.ts",
23
+ "require": "./dist/back.js",
24
+ "default": "./dist/back.js"
25
+ },
26
+ "./front": {
27
+ "types": "./dist/front.d.ts",
28
+ "require": "./dist/front.js",
29
+ "default": "./dist/front.js"
30
+ }
31
+ },
32
+ "typesVersions": {
33
+ "*": {
34
+ "back": [
35
+ "dist/back.d.ts"
36
+ ],
37
+ "front": [
38
+ "dist/front.d.ts"
39
+ ]
40
+ }
41
+ },
42
+ "files": [
43
+ "dist"
44
+ ],
45
+ "author": "Julio Fernandez",
46
+ "license": "ISC",
47
+ "dependencies": {
48
+ "@ai-sdk/anthropic": "^3.0.116",
49
+ "@ai-sdk/deepseek": "^2.0.29",
50
+ "@ai-sdk/google": "^3.0.64",
51
+ "@ai-sdk/groq": "^3.0.35",
52
+ "@ai-sdk/mistral": "^3.0.30",
53
+ "@ai-sdk/openai": "^3.0.53",
54
+ "@openrouter/ai-sdk-provider": "^2.8.0",
55
+ "ai": "^6.0.174",
56
+ "zod": "^4.3.6"
57
+ },
58
+ "peerDependencies": {
59
+ "react": ">=18.0.0",
60
+ "@kubernetes/client-node": ">=1.0.0"
61
+ },
62
+ "devDependencies": {
63
+ "@kwirthmagnify/kwirth-common": "^0.5.42",
64
+ "@mui/icons-material": "7.1.2",
65
+ "@mui/material": "7.1.2",
66
+ "@types/node": "^25.9.1",
67
+ "@types/react": "^18.3.0",
68
+ "typescript": "^5.4.0",
69
+ "@kubernetes/client-node": "^1.4.0"
70
+ },
71
+ "peerDependenciesMeta": {
72
+ "@kubernetes/client-node": {
73
+ "optional": true
74
+ },
75
+ "react": {
76
+ "optional": true
77
+ }
78
+ }
79
+ }