@astratra/ai 1.5.0 → 1.7.0

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.
@@ -0,0 +1,99 @@
1
+ 'use strict';
2
+ const { createTokenFileReader, serviceRequest, endpoint, AiServiceError } = require('./serviceHttp');
3
+
4
+ const LOCAL_VECTOR_MODEL = 'bge-m3-onnx-int8';
5
+ const LOCAL_VECTOR_DIMENSIONS = 1024;
6
+ const text = (value) => typeof value === 'string' && Boolean(value.trim());
7
+ const finite = (value) => typeof value === 'number' && Number.isFinite(value);
8
+ const array = (value, max, validate) => Array.isArray(value) && value.length > 0 && value.length <= max && value.every(validate);
9
+ const probability = (value) => finite(value) && value >= 0 && value <= 1;
10
+
11
+ function validPcmAudio(audio) {
12
+ if (typeof audio !== 'string' || !audio || audio.length % 4 || !/^[A-Za-z0-9+/]*={0,2}$/.test(audio)) return false;
13
+ const size = audio.length / 4 * 3 - (audio.endsWith('==') ? 2 : audio.endsWith('=') ? 1 : 0);
14
+ return size >= 6400 && size <= 960000 && size % 2 === 0;
15
+ }
16
+
17
+ function createLocalModelsClient(options = {}) {
18
+ const circuits = new Map();
19
+ const now = options.now || Date.now;
20
+ const token = createTokenFileReader({ tokenFile: options.tokenFile, read: options.readTokenFile, now, refreshMs: options.tokenRefreshMs });
21
+ const model = options.vectorModel || LOCAL_VECTOR_MODEL;
22
+ const dimensions = options.vectorDimensions || LOCAL_VECTOR_DIMENSIONS;
23
+ const circuit = (path) => {
24
+ if (!circuits.has(path)) circuits.set(path, { failures: 0, until: 0, probing: false });
25
+ return circuits.get(path);
26
+ };
27
+ const report = (error, route) => {
28
+ if (typeof options.onError === 'function') {
29
+ try { options.onError(error, route); } catch { /* Diagnostics must not break an optional model. */ }
30
+ }
31
+ };
32
+ async function call(path, body, settings, defaultTimeout, validate) {
33
+ const state = circuit(path);
34
+ if (!options.baseUrl || now() < state.until || state.probing) return null;
35
+ const probe = state.until > 0;
36
+ if (probe) state.probing = true;
37
+ try {
38
+ const bearer = await token();
39
+ const timeoutMs = settings.timeoutMs ?? options.timeoutMs ?? defaultTimeout;
40
+ const result = await serviceRequest(endpoint(options.baseUrl, path), {
41
+ fetch: options.fetch, timeoutMs, signal: settings.signal, body,
42
+ headers: { 'X-Delai-Ms': String(timeoutMs), ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}) }
43
+ });
44
+ const value = validate(result);
45
+ if (value === null) throw new AiServiceError('AI_SERVICE_RESPONSE');
46
+ Object.assign(state, { failures: 0, until: 0 });
47
+ return value;
48
+ } catch (error) {
49
+ if (settings.signal?.aborted) throw settings.signal.reason;
50
+ if (error.status >= 400 && error.status < 500) Object.assign(state, { failures: 0, until: 0 });
51
+ else {
52
+ state.failures += 1;
53
+ if (probe || state.failures >= (options.maxFailures ?? 3)) state.until = now() + (options.cooldownMs ?? 60000);
54
+ }
55
+ report(error, path);
56
+ return null;
57
+ } finally { state.probing = false; }
58
+ }
59
+ function invalid(path) { report(new AiServiceError('AI_SERVICE_INPUT'), path); return null; }
60
+ async function reclasser(question, passages, settings = {}) {
61
+ if (!text(question) || !array(passages, 50, (p) => typeof p === 'string')) return invalid('/reclasser');
62
+ return call('/reclasser', { question, passages }, settings, 1000, (data) => Array.isArray(data?.scores) && data.scores.length === passages.length && data.scores.every(finite) ? data.scores : null);
63
+ }
64
+ async function nli(paires, settings = {}) {
65
+ if (!array(paires, 20, (pair) => text(pair?.premisse) && text(pair?.hypothese))) return invalid('/nli');
66
+ return call('/nli', { paires }, settings, 1500, (data) => Array.isArray(data?.resultats) && data.resultats.length === paires.length && data.resultats.every((r) => probability(r?.accord) && probability(r?.neutre) && probability(r?.contradiction)) ? data.resultats : null);
67
+ }
68
+ async function entites(texte, etiquettes, settings = {}) {
69
+ if (!text(texte) || texte.length > 8000 || !array(etiquettes, 10, (label) => text(label) && label.length <= 50)) return invalid('/entites');
70
+ const labels = new Set(etiquettes.map((label) => label.trim()));
71
+ return call('/entites', { texte, etiquettes }, settings, 800, (data) => Array.isArray(data?.entites) && data.entites.every((e) => typeof e.texte === 'string' && labels.has(e.type) && Number.isInteger(e.debut) && Number.isInteger(e.fin) && e.debut >= 0 && e.fin > e.debut && e.fin <= texte.length && probability(e.score)) ? data.entites : null);
72
+ }
73
+ async function vecteurs(textes, settings = {}) {
74
+ if (!array(textes, 32, (t) => text(t) && t.length <= 2000)) return invalid('/vecteurs');
75
+ return call('/vecteurs', { textes }, settings, 1500, (data) => {
76
+ if (data?.modele !== model || data.dimensions !== dimensions || !Array.isArray(data.vecteurs) || data.vecteurs.length !== textes.length || !data.vecteurs.every((v) => Array.isArray(v) && v.length === dimensions && v.every(finite))) return null;
77
+ Object.defineProperties(data.vecteurs, { modele: { value: model }, dimensions: { value: dimensions } });
78
+ return data.vecteurs;
79
+ });
80
+ }
81
+ async function transcrire(audio, { langue, vocabulaire = '', ...settings } = {}) {
82
+ if (!validPcmAudio(audio) || !['fr', 'en', 'es', 'ln'].includes(langue) || typeof vocabulaire !== 'string' || vocabulaire.length > 600) return invalid('/transcrire');
83
+ return call('/transcrire', { audio, langue, vocabulaire }, settings, 15000, (data) => typeof data?.texte === 'string' && text(data.langue) && finite(data.logprob) && probability(data.sans_parole) && finite(data.duree_ms) && data.duree_ms >= 0
84
+ ? { texte: data.texte, langue: data.langue, logprob: data.logprob, sansParole: data.sans_parole, dureeMs: data.duree_ms } : null);
85
+ }
86
+ const disponible = (path) => Boolean(options.baseUrl) && now() >= circuit(path).until && !circuit(path).probing;
87
+ // English adapters plug directly into the package's generic source/mask APIs.
88
+ async function compare(pairs, settings = {}) {
89
+ if (!Array.isArray(pairs)) return invalid('/nli');
90
+ const results = await nli(pairs.map((pair) => ({ premisse: pair?.premise, hypothese: pair?.hypothesis })), settings);
91
+ return results?.map((result) => ({ entailment: result.accord, neutral: result.neutre, contradiction: result.contradiction })) ?? null;
92
+ }
93
+ async function entities(value, labels, settings = {}) {
94
+ const results = await entites(value, labels, settings);
95
+ return results?.map((entity) => ({ text: entity.texte, type: entity.type, start: entity.debut, end: entity.fin, score: entity.score })) ?? null;
96
+ }
97
+ return { reclasser, rerank: reclasser, nli, comparer: nli, compare, entites, entities, vecteurs, embed: vecteurs, transcrire, disponible, available: disponible };
98
+ }
99
+ module.exports = { createLocalModelsClient, LOCAL_VECTOR_MODEL, LOCAL_VECTOR_DIMENSIONS, validPcmAudio };
@@ -0,0 +1,258 @@
1
+ 'use strict';
2
+
3
+ const { createProviderRouter } = require('./providerRouter');
4
+ const { createOpenAICompatibleProvider } = require('./openaiCompatible');
5
+ const { createGeminiProvider } = require('./gemini');
6
+ const { createMemoryRoutingStore } = require('./routingState');
7
+ const { wholeSentences } = require('./answerText');
8
+ const { createInferenceQueue } = require('./providerLimits');
9
+
10
+ const COMPLEX = ['analyse ', 'analysez', 'compare ', 'comparez', 'explique en détail', 'rédige ', 'démontre ', 'évalue ', 'résume ', 'développe ', 'fais une synthèse', 'stratégie', 'recommandation', 'comment améliorer', 'quelles sont les causes', "plan d'action", 'programme de', 'argumentes', 'quelles mesures', 'bilan', 'rapport complet', 'que penses-tu de', 'analyze ', 'analyse ', 'compare ', 'evaluate ', 'strategy', 'detailed report'];
11
+ const MEDIUM = ["qu'est-ce qu", 'comment', 'explique', 'définis', "c'est quoi", 'kesako', 'dis-moi', 'parle-moi', 'quelle est', 'quels sont', 'quelles sont', 'pourquoi', 'what is', 'how to', 'can you', 'tell me', 'explain'];
12
+ const SIMPLE = ['bonjour', 'salut', 'merci', 'ok', 'oui', 'non', 'ça va', 'hello', 'bonsoir', "d'accord", 'parfait', 'super', 'cool', 'ciao', 'bonne journée', 'thanks', 'bye', 'good morning', 'good evening'];
13
+
14
+ function estimateRequestComplexity(input) {
15
+ const text = typeof input === 'string' ? input : (input?.messages || []).filter((m) => m.role === 'user').map((m) => m.text ?? m.content ?? '').join(' ');
16
+ const lower = text.toLowerCase();
17
+ const words = text.trim() ? text.trim().split(/\s+/).length : 0;
18
+ if (COMPLEX.some((word) => lower.includes(word)) || words > 40) return 'complex';
19
+ if (MEDIUM.some((word) => lower.includes(word))) return 'medium';
20
+ if (words <= 10 || SIMPLE.some((word) => lower.includes(word))) return 'simple';
21
+ return 'medium';
22
+ }
23
+
24
+ function estimateRequestTokens(request) {
25
+ // Include instructions, history, tool schemas and the entire output budget.
26
+ return Math.ceil(JSON.stringify(request).length / 3) + (request.maxTokens ?? 1200);
27
+ }
28
+
29
+ function freshState(now, state) {
30
+ const day = new Date(now).toISOString().slice(0, 10);
31
+ const next = { day, rpmWindow: [], rpdUsed: 0, tpdUsed: 0, cooldownUntil: 0, degradedUntil: 0, failures: 0, disabled: false, ...state };
32
+ if (next.day !== day) Object.assign(next, { day, rpdUsed: 0, tpdUsed: 0 });
33
+ if (next.degradedUntil > 0 && next.degradedUntil <= now) Object.assign(next, { degradedUntil: 0, failures: 0 });
34
+ next.rpmWindow = next.rpmWindow.filter((time) => now - time < 60000);
35
+ return next;
36
+ }
37
+ const aiError = (code) => Object.assign(new Error(code), { code });
38
+ const stopped = (signal) => { if (signal?.aborted) throw signal.reason; };
39
+ const keysOf = (value) => [...new Set((Array.isArray(value) ? value : [value]).filter((key) => typeof key === 'string' && key.trim()))];
40
+
41
+ function createConfiguredRouter(config = {}) {
42
+ const definitions = config.providers || [];
43
+ validateConfiguration(definitions, config);
44
+ if (config.store && (typeof config.store.read !== 'function' || typeof config.store.update !== 'function')) throw new TypeError('INVALID_ROUTING_STORE');
45
+ const store = config.store || createMemoryRoutingStore();
46
+ const now = config.now || Date.now;
47
+ const seen = new Set();
48
+ const cursors = new Map();
49
+ const queues = new Map(definitions.filter((provider) => provider.local).map((provider) => [provider.id, createInferenceQueue(provider)]));
50
+ const prefix = config.statePrefix || 'routing:';
51
+ const margins = { rpm: 0.75, rpd: 0.90, tpd: 0.85, ...(typeof config.quotaMargin === 'number' ? { rpm: config.quotaMargin, rpd: config.quotaMargin, tpd: config.quotaMargin } : config.quotaMargin) };
52
+ const cooldownMs = config.cooldownMs ?? 120000;
53
+ const degradedMs = config.degradedMs ?? 300000;
54
+ const maxFailures = config.maxFailures ?? 3;
55
+ const tokenBuffer = config.tokenBuffer ?? 1.2;
56
+ let closed = false;
57
+
58
+ async function change(key, update) {
59
+ seen.add(key);
60
+ try { return await store.update(prefix + key, update); }
61
+ catch { throw aiError('AI_STATE_UNAVAILABLE'); }
62
+ }
63
+ async function reserve(key, model, cost, allowCooling) {
64
+ return change(key, (state) => {
65
+ const s = freshState(now(), state);
66
+ const limited = s.disabled || s.degradedUntil > now() || (!allowCooling && s.cooldownUntil > now())
67
+ || (model.rpm != null && s.rpmWindow.length + 1 > Math.floor(model.rpm * margins.rpm))
68
+ || (model.rpd != null && s.rpdUsed + 1 > Math.floor(model.rpd * margins.rpd))
69
+ || (model.tpd != null && s.tpdUsed + cost > Math.floor(model.tpd * margins.tpd));
70
+ if (!limited) { s.rpmWindow.push(now()); s.rpdUsed += 1; s.tpdUsed += cost; }
71
+ return { state: s, value: !limited };
72
+ });
73
+ }
74
+ async function outcome(key, error) {
75
+ await change(key, (state) => {
76
+ const s = freshState(now(), state);
77
+ const status = error?.statusCode ?? error?.status;
78
+ if (!error) Object.assign(s, { failures: 0, degradedUntil: 0, cooldownUntil: 0 });
79
+ else if (status === 404) s.disabled = true;
80
+ else if (!['AI_LOCAL_QUEUE_FULL', 'AI_MODEL_RESERVED'].includes(error.code) && ![400, 413, 414, 422].includes(status)) {
81
+ if (status === 429 || status === 503 || error.name === 'TimeoutError') s.cooldownUntil = now() + (error.retryAfterMs ?? (cooldownMs + Math.floor(Math.random() * (config.cooldownJitterMs ?? 0))));
82
+ // A rate limit is not a broken model; repeated actual failures are.
83
+ if (status !== 429) {
84
+ s.failures += 1;
85
+ if (s.failures >= maxFailures) s.degradedUntil = now() + degradedMs;
86
+ }
87
+ }
88
+ return { state: s };
89
+ });
90
+ }
91
+
92
+ async function route(input, options = {}, context = {}) {
93
+ if (closed) throw aiError('AI_ROUTER_STOPPED');
94
+ const request = typeof input === 'string' ? { messages: [{ role: 'user', text: input }] } : input;
95
+ if (!request || !Array.isArray(request.messages)) throw new TypeError('AI_MESSAGES_REQUIRED');
96
+ const ctx = { ...context, ...options.context, signal: options.signal || context.signal };
97
+ stopped(ctx.signal);
98
+ const complexity = options.complexity || estimateRequestComplexity(request);
99
+ const images = request.messages.some((message) => message.images?.length || (Array.isArray(message.content) && message.content.some((part) => part.type === 'image_url')));
100
+ const usage = options.usage || (request.tools?.length ? 'tools' : images ? 'vision' : options.json ? 'json' : complexity === 'simple' ? 'quick' : 'chat');
101
+ const purpose = options.purpose || ctx.purpose || usage;
102
+ ctx.purpose = purpose;
103
+ ctx.timeoutMs = options.timeoutMs ?? (options.waitedOn === false ? config.backgroundTimeoutMs ?? 45000 : config.waitedTimeoutMs ?? 12000);
104
+ const estimated = options.estimatedTokens ?? estimateRequestTokens(request);
105
+ if (!Number.isFinite(estimated) || estimated < 0 || !Number.isFinite(ctx.timeoutMs) || ctx.timeoutMs <= 0) throw new TypeError('INVALID_ROUTING_REQUEST');
106
+ const cost = Math.ceil(estimated * tokenBuffer);
107
+ const byId = new Map(definitions.map((provider) => [provider.id, provider]));
108
+ const pool = new Map();
109
+ for (const definition of definitions) {
110
+ const selected = definition.keysByUsage?.[purpose] || definition.keys;
111
+ const source = typeof selected === 'function' ? await selected(ctx) : selected;
112
+ pool.set(definition.id, keysOf(source));
113
+ }
114
+ let candidates = options.candidates || config.usages?.[usage] || (usage === 'tools' ? config.usages?.pilot : null)
115
+ || definitions.flatMap((provider) => provider.models.map((model) => ({ provider: provider.id, model: model.id })));
116
+ candidates = candidates.map((entry) => {
117
+ const provider = byId.get(entry.provider);
118
+ const declared = provider?.models.find((model) => model.id === entry.model);
119
+ return provider && declared ? { ...declared, ...entry, extra: { ...declared.extra, ...entry.extra } } : null;
120
+ }).filter(Boolean);
121
+ candidates = candidates.filter((model) => {
122
+ const provider = byId.get(model.provider);
123
+ return !model.disabled && !options.exclude?.includes(`${provider.id}:${model.model}`)
124
+ && (!images || model.vision === true || (model.vision !== false && provider.vision === true))
125
+ && (images || config.reserveVision !== true || model.visionOnly !== true)
126
+ && (!model.languages || !options.language || model.languages.includes(options.language))
127
+ && (!model.maxInputTokens || cost <= model.maxInputTokens)
128
+ && (!model.noAnalytics || (!options.hasAnalytics && request.messages.length <= 3 && cost <= (model.maxInputTokens || 2000)));
129
+ });
130
+ const preferred = options.intent && config.intentRouting?.[options.intent]?.preferred || [];
131
+ candidates = candidates.map((model, index) => ({ model, index })).sort((a, b) => {
132
+ const rank = ({ model, index }) => {
133
+ const intent = preferred.indexOf(`${model.provider}:${model.model}`) >= 0 ? preferred.indexOf(`${model.provider}:${model.model}`) : preferred.indexOf(model.model);
134
+ if (intent >= 0) return intent;
135
+ const fits = !model.complexity || model.complexity.includes(complexity);
136
+ return preferred.length + (fits ? 0 : candidates.length) + (model.preview ? candidates.length * 2 : 0) + index;
137
+ };
138
+ return rank(a) - rank(b);
139
+ }).map(({ model }) => model);
140
+ const providers = [];
141
+ const expanded = [];
142
+ const metadata = new Map();
143
+ for (const candidate of candidates) {
144
+ const definition = byId.get(candidate.provider);
145
+ const keys = pool.get(definition.id);
146
+ const available = definition.local || keys.length;
147
+ if (!available) continue;
148
+ const slots = keys.length || 1;
149
+ const cursorKey = `${definition.id}:${candidate.model}:${purpose}`;
150
+ const start = (cursors.get(cursorKey) || 0) % slots;
151
+ cursors.set(cursorKey, start + 1);
152
+ for (let offset = 0; offset < slots; offset += 1) {
153
+ const slot = (start + offset) % slots;
154
+ const id = `configured_${providers.length}`;
155
+ // Never put any part of a credential in a state key or result.
156
+ const lane = definition.keysByUsage?.[purpose] ? purpose : typeof definition.keyLane === 'function' ? definition.keyLane(ctx) : '';
157
+ const key = `${definition.id}:${candidate.model}@${lane ? lane + ':' : ''}key-${slot + 1}`;
158
+ const stateKey = definition.sharedKeyQuotas ? `${definition.id}:${candidate.model}` : key;
159
+ const adapterOptions = {
160
+ id, models: [], fetch: config.fetch || globalThis.fetch, getKey: () => keys[slot] || 'local',
161
+ toRequest: (value) => value, detailed: true, external: !definition.local,
162
+ extra: definition.extra, endpoint: definition.url, url: definition.url
163
+ };
164
+ const adapter = definition.format === 'gemini' ? createGeminiProvider(adapterOptions) : createOpenAICompatibleProvider(adapterOptions);
165
+ const call = adapter.call;
166
+ const send = async (value, callCtx, model) => {
167
+ stopped(callCtx.signal);
168
+ if (!(await reserve(stateKey, candidate, cost, callCtx.allowCooling))) throw aiError('AI_MODEL_RESERVED');
169
+ try {
170
+ const answer = await call(value, callCtx, model);
171
+ await outcome(stateKey, null);
172
+ return answer;
173
+ } catch (error) {
174
+ stopped(Object.hasOwn(callCtx, 'callerSignal') ? callCtx.callerSignal : callCtx.signal);
175
+ await outcome(stateKey, error);
176
+ throw error;
177
+ }
178
+ };
179
+ adapter.call = (value, callCtx, model) => {
180
+ const queue = queues.get(definition.id);
181
+ if (!queue) return send(value, callCtx, model);
182
+ const queueSignal = globalThis.AbortSignal.any([callCtx.signal || new globalThis.AbortController().signal, globalThis.AbortSignal.timeout(callCtx.timeoutMs)]);
183
+ return queue.run(() => send(value, { ...callCtx, signal: queueSignal, callerSignal: callCtx.signal }, model), { signal: queueSignal });
184
+ };
185
+ providers.push(adapter);
186
+ expanded.push({ provider: id, model: candidate.model, extra: candidate.extra, maxTokens: candidate.maxTokens });
187
+ metadata.set(id, { provider: definition.id, model: candidate.model, key, stateKey });
188
+ }
189
+ }
190
+ if (!expanded.length) throw aiError(pool.size && [...pool.values()].some((keys) => keys.length) || definitions.some((p) => p.local) ? 'AI_NO_MATCH' : 'AI_NO_PROVIDER');
191
+ let allCooling = true;
192
+ for (const meta of metadata.values()) {
193
+ let state;
194
+ try { state = freshState(now(), await store.read(prefix + meta.stateKey)); }
195
+ catch { throw aiError('AI_STATE_UNAVAILABLE'); }
196
+ if (state.cooldownUntil <= now()) allCooling = false;
197
+ }
198
+ ctx.allowCooling = config.whenAllCooling === 'try' && allCooling;
199
+ const router = createProviderRouter({ providers, cooldownOn: () => false, maxFailures: Infinity, now });
200
+ const toolNames = new Set((request.tools || []).map((tool) => tool.name));
201
+ const accepts = options.accepts || ((answer) => request.tools?.length && answer.toolCalls?.length
202
+ ? answer.toolCalls.every((call) => call.id && toolNames.has(call.name) && (call.invalid || (call.args && typeof call.args === 'object' && !Array.isArray(call.args))))
203
+ : Boolean(answer.text) && !answer.toolCalls?.length);
204
+ try {
205
+ const result = await router.route(request, { candidates: expanded, accepts, partial: (answer) => Boolean(answer.cut && answer.text && !answer.toolCalls?.length) }, ctx);
206
+ const meta = metadata.get(result.provider);
207
+ if (result.partial) result.value = { ...result.value, text: wholeSentences(result.value.text) };
208
+ return { ...result, ...meta, usage, complexity, fallback: false };
209
+ } catch (error) {
210
+ stopped(ctx.signal);
211
+ if (error.errors?.some((item) => item.code === 'AI_STATE_UNAVAILABLE')) throw aiError('AI_STATE_UNAVAILABLE');
212
+ if (request.tools?.length && options.fallbackWithoutTools !== false) {
213
+ const clean = { ...request, tools: [] };
214
+ // Keep tool results in the transcript: they are already-read evidence.
215
+ const fallback = await route(clean, { ...options, usage: images ? 'vision' : 'chat', fallbackWithoutTools: false, accepts: (answer) => Boolean(answer.text) && !answer.toolCalls?.length }, context);
216
+ return { ...fallback, fallback: true };
217
+ }
218
+ // Transport messages may carry URLs, request bodies or credentials.
219
+ throw aiError(error.code || 'AI_UNAVAILABLE');
220
+ } finally { router.stop(); }
221
+ }
222
+ return {
223
+ route,
224
+ async ask(input, options, context) { return (await route(input, options, context)).value; },
225
+ async getStats() {
226
+ const stats = {};
227
+ for (const key of seen) stats[key] = freshState(now(), await store.read(prefix + key));
228
+ return stats;
229
+ },
230
+ async reset() { for (const key of seen) await change(key, () => ({ state: null })); },
231
+ stop() { closed = true; },
232
+ store
233
+ };
234
+ }
235
+
236
+ function validateConfiguration(providers, config) {
237
+ const ids = new Set();
238
+ for (const provider of providers) {
239
+ if (!provider.id || ids.has(provider.id)) throw new TypeError('INVALID_PROVIDER_ID');
240
+ ids.add(provider.id);
241
+ if (!['openai', 'gemini'].includes(provider.format)) throw new TypeError('INVALID_PROVIDER_FORMAT');
242
+ if (!provider.url) throw new TypeError('PROVIDER_URL_REQUIRED');
243
+ if (!Array.isArray(provider.models)) throw new TypeError('PROVIDER_MODELS_REQUIRED');
244
+ const models = new Set();
245
+ for (const model of provider.models) {
246
+ if (!model.id || models.has(model.id)) throw new TypeError('INVALID_MODEL_ID');
247
+ models.add(model.id);
248
+ for (const quota of ['rpm', 'rpd', 'tpd']) if (model[quota] != null && (!Number.isFinite(model[quota]) || model[quota] < 0)) throw new TypeError('INVALID_MODEL_QUOTA');
249
+ }
250
+ }
251
+ const margins = typeof config.quotaMargin === 'number' ? [config.quotaMargin] : Object.values(config.quotaMargin || {});
252
+ if (margins.some((value) => !Number.isFinite(value) || value <= 0 || value > 1)) throw new TypeError('INVALID_QUOTA_MARGIN');
253
+ if (config.whenAllCooling != null && !['skip', 'try'].includes(config.whenAllCooling)) throw new TypeError('INVALID_ROUTING_OPTION');
254
+ for (const name of ['cooldownMs', 'degradedMs', 'cooldownJitterMs']) if (config[name] != null && (!Number.isFinite(config[name]) || config[name] < 0)) throw new TypeError('INVALID_ROUTING_OPTION');
255
+ for (const name of ['waitedTimeoutMs', 'backgroundTimeoutMs', 'tokenBuffer', 'maxFailures']) if (config[name] != null && (!Number.isFinite(config[name]) || config[name] <= 0)) throw new TypeError('INVALID_ROUTING_OPTION');
256
+ }
257
+
258
+ module.exports = { createConfiguredRouter, estimateRequestComplexity, estimateRequestTokens };
@@ -104,6 +104,7 @@ function providerResult(id, answer, detailed) {
104
104
  /* The status reaches the router (429 → cooldown); the key never does. */
105
105
  const failure = new Error(`Provider "${id}" answered ${answer.status}.`);
106
106
  failure.statusCode = answer.status;
107
+ if (answer.retryAfterMs != null) failure.retryAfterMs = answer.retryAfterMs;
107
108
  throw failure;
108
109
  }
109
110
  if (detailed) return { text: answer.text === undefined ? null : answer.text, toolCalls: answer.toolCalls || [], cut: Boolean(answer.cut) };
@@ -28,6 +28,7 @@
28
28
  */
29
29
 
30
30
  const { AppError } = require('@astratra/core');
31
+ const { TOOL_RISKS } = require('./toolRegistry');
31
32
 
32
33
  const KINDS = ['read', 'write', 'confirm'];
33
34
  const NAME = /^[a-z][a-z0-9_]{0,63}$/;
@@ -82,6 +83,11 @@ function validateNativeTools(tools, options = {}) {
82
83
  }
83
84
  if (!isPlain(values) || !Object.values(values).every(isValue)) refuse('its summary does not give an object of strings and numbers');
84
85
  }
86
+ if (options.requireRisk) {
87
+ if (!['LOW', 'MEDIUM', 'HIGH'].includes(tool.risk)) refuse('its risk must be LOW, MEDIUM or HIGH');
88
+ if (tool.kind === 'write' && tool.risk !== 'LOW') refuse('a tool that writes alone must be LOW');
89
+ if (tool.kind === 'confirm' && tool.risk === 'LOW' && typeof tool.undo !== 'function') refuse('a LOW confirmation tool needs undo');
90
+ }
85
91
  if (typeof tool.run !== 'function') refuse('its run is not a function');
86
92
  if (tool.kind === 'confirm' && typeof tool.perform !== 'function') refuse('a tool to confirm needs perform');
87
93
  if (tool.kind === 'write' && typeof tool.undo !== 'function') refuse('a tool that writes alone needs undo');
@@ -117,7 +123,10 @@ class ToolTimeout extends Error {}
117
123
 
118
124
  /* Une promesse qui abandonne quand le signal s'interrompt, avec la raison du signal. */
119
125
  function abortable(promise, signal) {
120
- if (signal.aborted) return Promise.reject(signal.reason);
126
+ if (signal.aborted) {
127
+ promise.catch(() => {});
128
+ return Promise.reject(signal.reason);
129
+ }
121
130
  return new Promise((resolve, reject) => {
122
131
  const stop = () => reject(signal.reason);
123
132
  signal.addEventListener('abort', stop, { once: true });
@@ -158,6 +167,8 @@ function createToolCaller(options = {}) {
158
167
  const resultMax = options.resultMax || DEFAULT_RESULT_MAX;
159
168
  const messages = { ...MESSAGES, ...(options.messages || {}) };
160
169
  let steps = 0;
170
+ const exposure = options.exposure || context.exposure || { untrusted: false };
171
+ const useExposure = options.confirmationPolicy !== undefined || options.readsUntrusted || options.exposure || context.exposure;
161
172
 
162
173
  function bounded(data) {
163
174
  const json = JSON.stringify(data ?? null);
@@ -178,10 +189,24 @@ function createToolCaller(options = {}) {
178
189
  if (!tool) throw new Error(messages.unknownTool(name));
179
190
  if (invalid) throw new Error(messages.invalidArguments({ name, invalidReason, invalidDetail }));
180
191
  const toolSignal = globalThis.AbortSignal.any([signal, timeout.signal]);
181
- const found = await abortable(Promise.resolve().then(() => tool.run(args, { ...context, signal: toolSignal })), toolSignal);
192
+ toolSignal.throwIfAborted();
193
+ const toolContext = { ...context, signal: toolSignal, ...(useExposure ? { exposure } : {}) };
194
+ let effectiveTool = tool;
195
+ const found = await abortable(Promise.resolve().then(async () => {
196
+ const prepared = await tool.run(args, toolContext);
197
+ toolSignal.throwIfAborted();
198
+ if (options.readsUntrusted?.(tool, prepared)) exposure.untrusted = true;
199
+ if (tool.kind !== 'confirm' || options.confirmationPolicy === undefined) return prepared;
200
+ const waits = waitsForToolConfirmation(tool, { policy: options.confirmationPolicy, untrusted: exposure.untrusted || prepared?.confirm === true });
201
+ if (waits) return prepared;
202
+ if (typeof tool.undo !== 'function') throw new Error('Automatic confirmation requires undo.');
203
+ const done = await tool.perform(args, toolContext);
204
+ effectiveTool = { ...tool, kind: 'write' };
205
+ return done;
206
+ }), toolSignal);
182
207
  keep(found?.sources, found?.data);
183
- if (record) await record({ tool, args, found: found ?? {} });
184
- result = tool.kind === 'confirm' ? { data: bounded(found?.data), status: messages.waiting } : bounded(found?.data);
208
+ if (record) await record({ tool: effectiveTool, args, found: found ?? {} });
209
+ result = effectiveTool.kind === 'confirm' || (options.confirmationPolicy !== undefined && found?.confirm === true) ? { data: bounded(found?.data), status: messages.waiting } : bounded(found?.data);
185
210
  } catch (error) {
186
211
  if (signal.aborted) throw signal.reason;
187
212
  ok = false;
@@ -253,4 +278,18 @@ async function runToolLoop(options = {}) {
253
278
  return answerOf(await turn({ system: final, messages, tools: [] }));
254
279
  }
255
280
 
256
- module.exports = { validateNativeTools, toolSpecs, stepParams, createToolCaller, runToolLoop, NATIVE_TOOL_KINDS: KINDS };
281
+ /** A missing risk always waits when a confirmation policy is enabled. */
282
+ function toolRiskOf(tool) {
283
+ const risk = String(tool?.risk || '').toUpperCase();
284
+ return Object.hasOwn(TOOL_RISKS, risk) ? risk : 'UNKNOWN';
285
+ }
286
+ function waitsForToolConfirmation(tool, { policy = { threshold: 'MEDIUM' }, untrusted = false } = {}) {
287
+ if (tool?.kind !== 'confirm') return false;
288
+ if (untrusted || toolRiskOf(tool) === 'UNKNOWN') return true;
289
+ if (policy === 'always') return true;
290
+ if (policy === 'never') return false;
291
+ const threshold = policy.threshold || 'MEDIUM';
292
+ return TOOL_RISKS[toolRiskOf(tool)] >= (TOOL_RISKS[threshold] ?? TOOL_RISKS.UNKNOWN);
293
+ }
294
+
295
+ module.exports = { toolRiskOf, waitsForToolConfirmation, validateNativeTools, toolSpecs, stepParams, createToolCaller, runToolLoop, NATIVE_TOOL_KINDS: KINDS };
@@ -1,3 +1,4 @@
1
+ const { readRetryAfter } = require('./providerLimits');
1
2
  /**
2
3
  * Providers that speak the OpenAI chat format (Groq, Mistral, Cloudflare
3
4
  * Workers AI, gateways…): one request shape, one way to read the answer.
@@ -82,7 +83,10 @@ async function askChatModel(target, request, io = {}) {
82
83
  }),
83
84
  signal
84
85
  });
85
- if (!response.ok) return { status: response.status };
86
+ if (!response.ok) {
87
+ const retryAfterMs = readRetryAfter(response);
88
+ return { status: response.status, ...(retryAfterMs === null ? {} : { retryAfterMs }) };
89
+ }
86
90
  const answer = await response.json();
87
91
  const choice = (answer && answer.choices && answer.choices[0]) || {};
88
92
  const message = choice.message || {};
@@ -0,0 +1,45 @@
1
+ 'use strict';
2
+
3
+ function readRetryAfter(response, now = Date.now()) {
4
+ const value = response?.headers?.get?.('retry-after');
5
+ if (value == null || !String(value).trim()) return null;
6
+ const seconds = Number(value);
7
+ if (Number.isFinite(seconds)) return seconds >= 0 ? Math.round(seconds * 1000) : null;
8
+ const date = Date.parse(value);
9
+ return Number.isFinite(date) ? Math.max(0, date - now) : null;
10
+ }
11
+
12
+ // A bounded local inference queue: do not load a CPU server with an unlimited
13
+ // number of simultaneous calls. A slot is released on every outcome/abort.
14
+ function createInferenceQueue({ maxConcurrent = 8, maxQueue = 20 } = {}) {
15
+ if (!Number.isInteger(maxConcurrent) || maxConcurrent < 1 || !Number.isInteger(maxQueue) || maxQueue < 0) throw new TypeError('INVALID_INFERENCE_QUEUE');
16
+ const waiting = [];
17
+ let active = 0;
18
+ const error = (code) => Object.assign(new Error(code), { code });
19
+ function acquire(signal) {
20
+ if (signal?.aborted) return Promise.reject(signal.reason);
21
+ if (active < maxConcurrent) { active += 1; return Promise.resolve(); }
22
+ if (waiting.length >= maxQueue) return Promise.reject(error('AI_LOCAL_QUEUE_FULL'));
23
+ return new Promise((resolve, reject) => {
24
+ const waiter = { resolve, reject, signal, abort: null };
25
+ waiter.abort = () => { const at = waiting.indexOf(waiter); if (at >= 0) waiting.splice(at, 1); reject(signal.reason); };
26
+ signal?.addEventListener('abort', waiter.abort, { once: true });
27
+ waiting.push(waiter);
28
+ });
29
+ }
30
+ function release() {
31
+ const waiter = waiting.shift();
32
+ if (!waiter) { active -= 1; return; }
33
+ waiter.signal?.removeEventListener('abort', waiter.abort);
34
+ waiter.resolve();
35
+ }
36
+ return {
37
+ async run(task, { signal } = {}) {
38
+ await acquire(signal);
39
+ try { signal?.throwIfAborted(); return await task(); }
40
+ finally { release(); }
41
+ },
42
+ stats: () => ({ active, waiting: waiting.length })
43
+ };
44
+ }
45
+ module.exports = { readRetryAfter, createInferenceQueue };
@@ -0,0 +1,87 @@
1
+ 'use strict';
2
+
3
+ // update() is an atomic read/modify/write boundary. Database adapters must
4
+ // serialize it across processes (Redis CAS, PostgreSQL row/advisory locks).
5
+ function createMemoryRoutingStore() {
6
+ const states = new Map();
7
+ const pending = new Map();
8
+ const clone = (value) => value == null ? null : globalThis.structuredClone(value);
9
+ async function update(key, change) {
10
+ const previous = pending.get(key) || Promise.resolve();
11
+ const current = previous.catch(() => {}).then(() => {
12
+ const { state, value } = change(clone(states.get(key)));
13
+ if (state == null) states.delete(key);
14
+ else states.set(key, clone(state));
15
+ return value;
16
+ });
17
+ pending.set(key, current);
18
+ try { return await current; }
19
+ finally { if (pending.get(key) === current) pending.delete(key); }
20
+ }
21
+ return {
22
+ update,
23
+ async read(key) { await pending.get(key); return clone(states.get(key)); }
24
+ };
25
+ }
26
+
27
+ const CAS = `
28
+ local old = redis.call('GET', KEYS[1])
29
+ if (old or '') ~= ARGV[1] then return 0 end
30
+ if ARGV[2] == '' then redis.call('DEL', KEYS[1])
31
+ else redis.call('SET', KEYS[1], ARGV[2], 'PX', ARGV[3]) end
32
+ return 1`;
33
+
34
+ // The client is owned by the consumer. No connection or silent RAM fallback.
35
+ function createRedisRoutingStore({ client, prefix = 'astratra:ai:', ttlMs = 172800000, maxRetries = 100 } = {}) {
36
+ if (!Number.isFinite(ttlMs) || ttlMs < 86400000 || !Number.isInteger(maxRetries) || maxRetries < 1) throw new TypeError('INVALID_REDIS_STATE_OPTIONS');
37
+ if (!client || typeof client.eval !== 'function' || typeof client.get !== 'function') throw new TypeError('REDIS_CLIENT_REQUIRED');
38
+ return {
39
+ async read(key) {
40
+ const raw = await client.get(prefix + key);
41
+ return raw == null ? null : JSON.parse(raw);
42
+ },
43
+ async update(key, change) {
44
+ for (let attempt = 0; attempt < maxRetries; attempt += 1) {
45
+ const raw = await client.get(prefix + key);
46
+ const { state, value } = change(raw == null ? null : JSON.parse(raw));
47
+ const stored = await client.eval(CAS, {
48
+ keys: [prefix + key], arguments: [raw || '', state == null ? '' : JSON.stringify(state), String(ttlMs)]
49
+ });
50
+ if (Number(stored) === 1) return value;
51
+ }
52
+ throw new Error('AI_STATE_CONTENTION');
53
+ }
54
+ };
55
+ }
56
+
57
+ function createPostgresRoutingStore({ pool, table = 'ai_routing_state' } = {}) {
58
+ if (!/^[a-z_][a-z0-9_]*$/.test(table)) throw new TypeError('INVALID_STATE_TABLE');
59
+ if (!pool || typeof pool.connect !== 'function') throw new TypeError('POSTGRES_POOL_REQUIRED');
60
+ return {
61
+ // Explicit: construction does not mutate a consumer's database.
62
+ async initialize() { await pool.query(`CREATE TABLE IF NOT EXISTS ${table} (key text PRIMARY KEY, state jsonb NOT NULL)`); },
63
+ async read(key) {
64
+ const { rows } = await pool.query(`SELECT state FROM ${table} WHERE key = $1`, [key]);
65
+ return rows[0]?.state ?? null;
66
+ },
67
+ async update(key, change) {
68
+ const connection = await pool.connect();
69
+ try {
70
+ await connection.query('BEGIN');
71
+ // Lock also protects first insertion; SELECT FOR UPDATE alone does not.
72
+ await connection.query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [`${table}:${key}`]);
73
+ const { rows } = await connection.query(`SELECT state FROM ${table} WHERE key = $1`, [key]);
74
+ const { state, value } = change(rows[0]?.state ?? null);
75
+ if (state == null) await connection.query(`DELETE FROM ${table} WHERE key = $1`, [key]);
76
+ else await connection.query(`INSERT INTO ${table} (key, state) VALUES ($1, $2::jsonb) ON CONFLICT (key) DO UPDATE SET state = EXCLUDED.state`, [key, JSON.stringify(state)]);
77
+ await connection.query('COMMIT');
78
+ return value;
79
+ } catch (error) {
80
+ await connection.query('ROLLBACK');
81
+ throw error;
82
+ } finally { connection.release(); }
83
+ }
84
+ };
85
+ }
86
+
87
+ module.exports = { createMemoryRoutingStore, createRedisRoutingStore, createPostgresRoutingStore };