@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.
package/src/agentLoop.js CHANGED
@@ -1,6 +1,9 @@
1
1
  const { AppError } = require('@astratra/core');
2
2
 
3
3
  const DEFAULT_MAX_STEPS = 5;
4
+ const DEFAULT_LOOP_THRESHOLDS = Object.freeze({ reminder: 3, firmReminder: 5, stop: 8 });
5
+ const DEFAULT_SPILL_THRESHOLD = 12_000;
6
+ const SPILL_TOOL_NAME = 'read_spilled_result';
4
7
 
5
8
  async function runAgentLoop({
6
9
  prompt,
@@ -17,6 +20,12 @@ async function runAgentLoop({
17
20
  toolTimeoutMs,
18
21
  maxMs,
19
22
  finalInstruction,
23
+ loopGuard = {},
24
+ spill = {},
25
+ confirmationPolicy,
26
+ riskAnalyzers = [],
27
+ pendingActions,
28
+ onEvent,
20
29
  now = Date.now
21
30
  }) {
22
31
  if (!registry) throw new AppError('agentLoop requires a registry', 500);
@@ -26,6 +35,12 @@ async function runAgentLoop({
26
35
  }
27
36
 
28
37
  const messages = Array.isArray(history) ? [...history] : [];
38
+ const loopCounts = new Map();
39
+ const spillStore = spill.store || createMemorySpillStore();
40
+ const spillThreshold = Number.isFinite(spill.threshold) && spill.threshold >= 0 ? spill.threshold : DEFAULT_SPILL_THRESHOLD;
41
+ const thresholds = { ...DEFAULT_LOOP_THRESHOLDS, ...loopGuard };
42
+ const spills = new Map();
43
+ if (typeof spillStore.set !== 'function' || typeof spillStore.get !== 'function') throw new AppError('spill.store requires set() and get()', 500);
29
44
  messages.push({ role: 'user', content: prompt });
30
45
  const started = now();
31
46
 
@@ -53,13 +68,28 @@ async function runAgentLoop({
53
68
  const outOfTime = () => Number.isFinite(maxMs) && now() - started >= maxMs;
54
69
 
55
70
  for (let step = 0; step < maxSteps && !outOfTime(); step += 1) {
56
- const response = await askModel(buildPrompt(registry, userRole, messages));
71
+ const spillInstruction = spills.size ? `\n### Lire un résultat mis de côté\nAppelle <tool_call name="${SPILL_TOOL_NAME}">{"id":"référence","start":0,"length":4000}</tool_call> pour relire une tranche.` : '';
72
+ const response = await askModel(buildPrompt(registry, userRole, messages) + spillInstruction);
57
73
  const toolCall = parseToolCall(response);
58
74
 
59
75
  if (!toolCall) {
60
76
  return response;
61
77
  }
62
78
 
79
+ if (toolCall.name === SPILL_TOOL_NAME) {
80
+ const id = String(toolCall.params.id || '');
81
+ const stored = spills.get(id);
82
+ let result;
83
+ if (!stored) result = { error: 'spill_not_found' };
84
+ else {
85
+ const start = Math.max(0, Math.floor(Number(toolCall.params.start) || 0));
86
+ const length = Math.min(12_000, Math.max(0, Math.floor(Number(toolCall.params.length) || 4000)));
87
+ const value = await spillStore.get(id);
88
+ result = typeof value === 'string' ? { id, start, totalLength: value.length, text: value.slice(start, start + length) } : { error: 'spill_not_found' };
89
+ }
90
+ messages.push({ role: 'assistant', content: response }, { role: 'tool', content: `<tool_result name="${SPILL_TOOL_NAME}">${JSON.stringify(result)}</tool_result>` });
91
+ continue;
92
+ }
63
93
  const tool = registry.getToolByName(toolCall.name);
64
94
  if (!tool) {
65
95
  throw new AppError(`Tool "${toolCall.name}" is not registered`, 400);
@@ -73,8 +103,41 @@ async function runAgentLoop({
73
103
  // runs. Denying doesn't crash the loop: the model gets told and can
74
104
  // adjust course (ask something else, explain, stop), same as it would
75
105
  // handle any other tool result.
76
- if (typeof confirmTool === 'function') {
77
- const approved = await confirmTool(toolCall, ctx);
106
+ const normalizedCall = `${tool.name}:${stableStringify(toolCall.params)}`;
107
+ const repetitions = (loopCounts.get(normalizedCall) || 0) + 1;
108
+ loopCounts.set(normalizedCall, repetitions);
109
+ if (repetitions >= thresholds.stop) {
110
+ const reason = `Boucle arrêtée : l'appel ${tool.name} a été répété ${repetitions} fois.`;
111
+ const event = { type: 'tool_loop_stopped', name: tool.name, repetitions, reason };
112
+ if (typeof onEvent === 'function') onEvent(event);
113
+ return reason;
114
+ }
115
+ if (repetitions === thresholds.reminder || repetitions === thresholds.firmReminder) {
116
+ const reminder = repetitions === thresholds.reminder
117
+ ? `Rappel : cet appel identique a déjà été effectué ${repetitions} fois. Change de stratégie si le résultat ne suffit pas.`
118
+ : `Rappel ferme : cet appel identique a déjà été effectué ${repetitions} fois. Ne le répète plus sans modifier les arguments.`;
119
+ messages.push({ role: 'system', content: reminder });
120
+ if (typeof onEvent === 'function') onEvent({ type: 'tool_loop_warning', name: tool.name, repetitions, message: reminder });
121
+ }
122
+
123
+ let requiresConfirmation = typeof confirmTool === 'function';
124
+ if (confirmationPolicy !== undefined) {
125
+ let risk = tool.risk || 'UNKNOWN';
126
+ for (const analyze of riskAnalyzers) {
127
+ const analyzed = await analyze(toolCall, ctx, tool);
128
+ if (analyzed !== undefined && riskValue(analyzed) > riskValue(risk)) risk = String(analyzed).toUpperCase();
129
+ }
130
+ requiresConfirmation = shouldConfirm(confirmationPolicy, risk);
131
+ }
132
+ if (requiresConfirmation) {
133
+ let approved;
134
+ if (typeof confirmTool === 'function') approved = await confirmTool(toolCall, ctx);
135
+ else if (pendingActions && typeof pendingActions.propose === 'function') {
136
+ const proposed = await pendingActions.propose({ action: tool.name, payload: toolCall.params, description: `Appel ${tool.name} (${tool.risk || 'UNKNOWN'})`, proposedBy: ctx.userId, tenant: ctx.tenantId });
137
+ approved = false;
138
+ messages.push({ role: 'assistant', content: response }, { role: 'tool', content: `<tool_result name="${tool.name}">${JSON.stringify({ pending: true, actionId: proposed.action.id })}</tool_result>` });
139
+ continue;
140
+ } else approved = false;
78
141
  if (!approved) {
79
142
  messages.push({ role: 'assistant', content: response });
80
143
  messages.push({
@@ -100,13 +163,25 @@ async function runAgentLoop({
100
163
  }
101
164
  if (masker && tool.external === true) result = masker.unmaskDeep(result);
102
165
  const serialized = JSON.stringify(result);
166
+ const modelSerialized = masker ? masker.mask(serialized) : serialized;
103
167
  /* Your own data (a class list, a file) carries names the register may not
104
168
  know: the detector reads the result before it can reach the prompt. */
105
169
  if (masker && tool.external !== true && typeof masker.maskAsync === 'function') await masker.maskAsync(String(serialized));
106
170
  messages.push({ role: 'assistant', content: response });
171
+ let modelResult = serialized;
172
+ if (serialized.length > spillThreshold) {
173
+ const id = createSpillId();
174
+ try {
175
+ await spillStore.set(id, serialized);
176
+ spills.set(id, true);
177
+ modelResult = JSON.stringify({ spilled: true, id, totalLength: serialized.length, excerpt: modelSerialized.slice(0, 1500), readTool: SPILL_TOOL_NAME });
178
+ } catch (_error) {
179
+ modelResult = JSON.stringify({ error: 'result_storage_failed' });
180
+ }
181
+ }
107
182
  messages.push({
108
183
  role: 'tool',
109
- content: `<tool_result name="${tool.name}">${serialized}</tool_result>`
184
+ content: `<tool_result name="${tool.name}">${modelResult}</tool_result>`
110
185
  });
111
186
  }
112
187
 
@@ -121,6 +196,24 @@ async function runAgentLoop({
121
196
  throw new AppError(`agentLoop reached maxSteps (${maxSteps}) before a final answer`, 500);
122
197
  }
123
198
 
199
+ function stableStringify(value) {
200
+ if (value === null || typeof value !== 'object') return JSON.stringify(value);
201
+ if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
202
+ return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
203
+ }
204
+ function riskValue(risk) { return ({ LOW: 0, MEDIUM: 1, HIGH: 2, UNKNOWN: 3 })[String(risk).toUpperCase()] ?? 3; }
205
+ function shouldConfirm(policy, risk) {
206
+ if (policy === 'always') return true;
207
+ if (policy === 'never') return false;
208
+ const threshold = typeof policy === 'object' && policy ? policy.threshold : policy;
209
+ return risk === 'UNKNOWN' || riskValue(risk) >= riskValue(threshold);
210
+ }
211
+ function createMemorySpillStore() {
212
+ const values = new Map();
213
+ return { async set(id, value) { values.set(id, value); }, async get(id) { return values.get(id); } };
214
+ }
215
+ function createSpillId() { return `spill_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`; }
216
+
124
217
  async function runTool(tool, params, ctx, timeoutMs) {
125
218
  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return tool.handler(params, ctx);
126
219
  let timer;
@@ -200,5 +293,8 @@ function estimateTokens(text) {
200
293
  }
201
294
 
202
295
  module.exports = {
203
- runAgentLoop
296
+ runAgentLoop,
297
+ createMemorySpillStore,
298
+ DEFAULT_LOOP_THRESHOLDS,
299
+ DEFAULT_SPILL_THRESHOLD
204
300
  };
@@ -0,0 +1,72 @@
1
+ 'use strict';
2
+
3
+ // Only reads the supplied environment object. Never opens an .env file.
4
+ function readAiConfigFromEnv({ env = process.env, prefix = 'IA_' } = {}) {
5
+ const read = (name) => env[prefix + name];
6
+ const json = (name, fallback) => {
7
+ if (!read(name)) return fallback;
8
+ try { return JSON.parse(read(name)); }
9
+ catch { throw new TypeError(`INVALID_AI_CONFIG_${name}`); }
10
+ };
11
+ const number = (name, fallback) => {
12
+ if (read(name) == null || read(name) === '') return fallback;
13
+ const value = Number(read(name));
14
+ if (!Number.isFinite(value) || value < 0) throw new TypeError(`INVALID_AI_CONFIG_${name}`);
15
+ return value;
16
+ };
17
+ const boolean = (name, fallback) => {
18
+ if (!read(name)) return fallback;
19
+ if (!['true', 'false', '1', '0'].includes(read(name))) throw new TypeError(`INVALID_AI_CONFIG_${name}`);
20
+ return ['true', '1'].includes(read(name));
21
+ };
22
+ const providers = json('PROVIDERS', []);
23
+ if (!Array.isArray(providers)) throw new TypeError('INVALID_AI_CONFIG_PROVIDERS');
24
+ const usages = {};
25
+ for (const usage of ['quick', 'chat', 'tools', 'pilot', 'json', 'vision']) {
26
+ const list = json(`MODELS_${usage.toUpperCase()}`, undefined);
27
+ if (list !== undefined) {
28
+ if (!Array.isArray(list) || list.some((entry) => !entry?.provider || !entry.model)) throw new TypeError(`INVALID_AI_CONFIG_MODELS_${usage.toUpperCase()}`);
29
+ usages[usage] = list;
30
+ }
31
+ }
32
+ const config = {
33
+ providers: providers.map((provider) => {
34
+ const stem = provider.envName || provider.id?.toUpperCase().replace(/[^A-Z0-9]/g, '_');
35
+ if (!stem) throw new TypeError('INVALID_AI_CONFIG_PROVIDER_ID');
36
+ // Re-read keys at every request: settings screens can replace them live.
37
+ const keys = (ctx = {}) => readEnvironmentKeys(ctx.env || env, `${prefix}${stem}_KEY`);
38
+ return { ...provider, url: read(`${stem}_URL`) || provider.url, local: boolean(`${stem}_LOCAL`, provider.local), keys };
39
+ }),
40
+ usages,
41
+ intentRouting: json('INTENT_ROUTING', {}),
42
+ statePrefix: read('STATE_PREFIX') || 'routing:',
43
+ quotaMargin: json('QUOTA_MARGIN', { rpm: 0.75, rpd: 0.9, tpd: 0.85 }),
44
+ tokenBuffer: number('TOKEN_BUFFER', 1.2),
45
+ waitedTimeoutMs: number('WAITED_TIMEOUT_MS', 12000),
46
+ backgroundTimeoutMs: number('BACKGROUND_TIMEOUT_MS', 45000),
47
+ cooldownMs: number('COOLDOWN_MS', 120000),
48
+ cooldownJitterMs: number('COOLDOWN_JITTER_MS', 0),
49
+ degradedMs: number('DEGRADED_MS', 300000),
50
+ maxFailures: number('MAX_FAILURES', 3),
51
+ whenAllCooling: read('WHEN_ALL_COOLING') || 'skip',
52
+ reserveVision: boolean('RESERVE_VISION', false),
53
+ localModels: { baseUrl: read('MODELS_URL'), tokenFile: read('MODELS_TOKEN_FILE') },
54
+ language: { baseUrl: read('LANGUAGE_URL'), timeoutMs: number('LANGUAGE_TIMEOUT_MS', 800) },
55
+ voice: {
56
+ piper: { baseUrl: read('TTS_URL'), tokenFile: read('TTS_TOKEN_FILE') },
57
+ groq: { url: read('GROQ_WHISPER_URL') || 'https://api.groq.com/openai/v1/audio/transcriptions', keys: () => readEnvironmentKeys(env, prefix + 'GROQ_KEY'), models: json('GROQ_WHISPER_MODELS', ['whisper-large-v3-turbo', 'whisper-large-v3']) },
58
+ cloudflare: { url: read('CLOUDFLARE_WHISPER_URL') || (read('CLOUDFLARE_ACCOUNT_ID') ? `https://api.cloudflare.com/client/v4/accounts/${read('CLOUDFLARE_ACCOUNT_ID')}/ai/run/@cf/openai/whisper-large-v3-turbo` : undefined), keys: () => readEnvironmentKeys(env, prefix + 'CLOUDFLARE_KEY') },
59
+ gemini: { endpoint: read('GEMINI_TTS_ENDPOINT'), keys: () => readEnvironmentKeys(env, prefix + 'GEMINI_KEY'), models: json('GEMINI_TTS_MODELS', ['gemini-2.5-flash-preview-tts']), voice: read('GEMINI_TTS_VOICE') || 'Aoede' }
60
+ }
61
+ };
62
+ if (!['skip', 'try'].includes(config.whenAllCooling)) throw new TypeError('INVALID_AI_CONFIG_WHEN_ALL_COOLING');
63
+ return config;
64
+ }
65
+
66
+ function readEnvironmentKeys(env, name) {
67
+ // Sparse suffixes work as well; a missing _2 must not hide _3.
68
+ const names = Object.keys(env).filter((key) => key === name || (key.startsWith(name + '_') && /^\d+$/.test(key.slice(name.length + 1))))
69
+ .sort((a, b) => (a === name ? 0 : Number(a.slice(name.length + 1))) - (b === name ? 0 : Number(b.slice(name.length + 1))));
70
+ return [...new Set(names.map((key) => env[key]).filter((key) => typeof key === 'string' && key.trim()))];
71
+ }
72
+ module.exports = { readAiConfigFromEnv, readEnvironmentKeys };
package/src/gemini.js CHANGED
@@ -1,3 +1,4 @@
1
+ const { readRetryAfter } = require('./providerLimits');
1
2
  /**
2
3
  * L'API Gemini de Google (generateContent) : la même requête que le format
3
4
  * OpenAI (consigne, transcription, outils, photos), traduite dans la sienne,
@@ -80,10 +81,13 @@ async function askGeminiModel(model, request, io = {}) {
80
81
  const response = await io.fetch(`${io.endpoint || DEFAULT_ENDPOINT}/${model}:generateContent`, {
81
82
  method: 'POST',
82
83
  headers: { 'content-type': 'application/json', 'x-goog-api-key': io.key },
83
- body: JSON.stringify(requestBody(model, request, io.noSystemInstruction || noSystemInstructionByDefault)),
84
+ body: JSON.stringify({ ...requestBody(model, request, io.noSystemInstruction || noSystemInstructionByDefault), ...(io.extra || {}) }),
84
85
  signal
85
86
  });
86
- if (!response.ok) return { status: response.status };
87
+ if (!response.ok) {
88
+ const retryAfterMs = readRetryAfter(response);
89
+ return { status: response.status, ...(retryAfterMs === null ? {} : { retryAfterMs }) };
90
+ }
87
91
  const answer = await response.json();
88
92
  const candidate = (answer && answer.candidates && answer.candidates[0]) || {};
89
93
  const parts = (candidate.content && candidate.content.parts) || [];
@@ -125,6 +129,7 @@ function createGeminiProvider(options = {}) {
125
129
  return {
126
130
  id,
127
131
  models: options.models || [],
132
+ ...(options.external === false ? { external: false } : {}),
128
133
  ...(typeof options.lane === 'function' ? { lane: options.lane } : {}),
129
134
  async available(ctx = {}) {
130
135
  return Boolean(await options.getKey(ctx));
@@ -142,7 +147,8 @@ function createGeminiProvider(options = {}) {
142
147
  signal: ctx.signal,
143
148
  timeoutMs: ctx.timeoutMs || options.timeoutMs,
144
149
  endpoint: options.endpoint,
145
- noSystemInstruction: options.noSystemInstruction
150
+ noSystemInstruction: options.noSystemInstruction,
151
+ extra: { ...(options.extra || {}), ...(model.extra || {}) }
146
152
  });
147
153
  return providerResult(id, answer, options.detailed);
148
154
  }