@astratra/ai 1.0.0 → 1.0.2

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/README.md CHANGED
@@ -15,7 +15,7 @@ d'agent.
15
15
  const { createProviderRouter } = require('@astratra/ai');
16
16
 
17
17
  const router = createProviderRouter({
18
- redisUrl: process.env.REDIS_URL, // optionnel — état partagé entre instances, repli RAM si absent/injoignable
18
+ redisUrl: process.env.REDIS_URL, // optionnel — quotas atomiques partagés entre instances
19
19
  intentRouting: {
20
20
  summarize: { preferred: ['fast-model'] }
21
21
  },
@@ -29,15 +29,19 @@ const router = createProviderRouter({
29
29
  });
30
30
 
31
31
  const reponse = await router.ask('Résume ceci.', { complexity: 'simple', estimatedTokens: 200 });
32
- router.getStats(); // usage RPM/RPD/TPD par modèle, état cooldown/dégradé
32
+ router.getStats(); // usage RPM/RPD/TPD par "providerId:modelId", état cooldown/dégradé
33
33
  router.stop(); // arrête le timer de reset minuit et ferme le lien Redis, s'il existe
34
34
  ```
35
35
 
36
36
  Les providers sont essayés dans l'ordre du tableau que vous fournissez —
37
37
  l'ordre de fallback est votre décision, pas figé dans le package. Les
38
38
  quotas RPM/RPD/TPD, le cooldown après 429 avec jitter et la dégradation
39
- après échecs répétés sont suivis par modèle. Les compteurs journaliers se
40
- réinitialisent automatiquement à minuit local.
39
+ après échecs répétés sont suivis par couple `providerId:modelId`. Avec
40
+ `redisUrl`, la réservation des quotas est atomique entre instances avant
41
+ l'appel du provider. Sans Redis, ou si Redis devient indisponible, le routeur
42
+ continue avec des compteurs RAM locaux : ce repli ne peut pas garantir un
43
+ quota distribué. Les compteurs journaliers se réinitialisent automatiquement
44
+ à minuit.
41
45
 
42
46
  ## Registre d'outils
43
47
 
package/package.json CHANGED
@@ -1,7 +1,10 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
5
+ "engines": {
6
+ "node": ">=20"
7
+ },
5
8
  "main": "src/index.js",
6
9
  "types": "src/index.d.ts",
7
10
  "type": "commonjs",
package/src/index.d.ts CHANGED
@@ -50,6 +50,7 @@ export interface ProviderStats {
50
50
 
51
51
  export interface ProviderRouter {
52
52
  ask(prompt: string, request?: ProviderRequest, ctx?: Record<string, unknown>): Promise<unknown>;
53
+ /** Les entrées sont indexées par "providerId:modelId". */
53
54
  getStats(): Record<string, ProviderStats>;
54
55
  stop(): void;
55
56
  }
@@ -1,10 +1,39 @@
1
1
  const { AppError } = require('@astratra/core');
2
+ const { randomUUID } = require('crypto');
2
3
 
3
4
  const DEFAULT_COOLDOWN_MS = 60 * 1000;
4
5
  const DEFAULT_COOLDOWN_JITTER_MS = 8 * 1000;
5
6
  const DEFAULT_MAX_FAILURES = 3;
6
7
  const DEFAULT_DEGRADED_MS = 5 * 60 * 1000;
7
8
  const RPM_WINDOW_MS = 60 * 1000;
9
+ const RESERVE_USAGE_SCRIPT = `
10
+ local now = tonumber(ARGV[1])
11
+ local rpmLimit = tonumber(ARGV[2])
12
+ local rpdLimit = tonumber(ARGV[3])
13
+ local tpdLimit = tonumber(ARGV[4])
14
+ local tokenCost = tonumber(ARGV[5])
15
+ local reservationId = ARGV[6]
16
+ local rpmWindowMs = tonumber(ARGV[7])
17
+ local rpmTtl = tonumber(ARGV[8])
18
+ local dayTtl = tonumber(ARGV[9])
19
+
20
+ redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now - rpmWindowMs)
21
+ if rpmLimit > 0 and redis.call('ZCARD', KEYS[1]) >= rpmLimit then return 0 end
22
+
23
+ local rpdUsed = tonumber(redis.call('GET', KEYS[2]) or '0')
24
+ if rpdLimit > 0 and rpdUsed + 1 > rpdLimit then return 0 end
25
+
26
+ local tpdUsed = tonumber(redis.call('GET', KEYS[3]) or '0')
27
+ if tpdLimit > 0 and tpdUsed + tokenCost > tpdLimit then return 0 end
28
+
29
+ redis.call('ZADD', KEYS[1], now, reservationId)
30
+ redis.call('EXPIRE', KEYS[1], rpmTtl)
31
+ redis.call('INCRBY', KEYS[2], 1)
32
+ redis.call('EXPIRE', KEYS[2], dayTtl)
33
+ redis.call('INCRBY', KEYS[3], tokenCost)
34
+ redis.call('EXPIRE', KEYS[3], dayTtl)
35
+ return 1
36
+ `;
8
37
 
9
38
  function createProviderRouter(config = {}) {
10
39
  const providers = Array.isArray(config.providers) ? config.providers : [];
@@ -34,20 +63,21 @@ function createProviderRouter(config = {}) {
34
63
 
35
64
  for (const candidate of candidates) {
36
65
  const { provider, model } = candidate;
37
- if (!isModelAvailable(state, model, request)) continue;
66
+ const key = modelKey(provider, model);
67
+ if (!isModelAvailable(state, key, model, request)) continue;
68
+ if (!await redis.reserveUsage(key, model, request)) continue;
38
69
 
39
- reserveUsage(state, model, request);
40
- redis.mirrorUsage(model.id, state.models[model.id]);
70
+ reserveUsage(state, key, request);
41
71
 
42
72
  try {
43
73
  const result = await provider.call(prompt, ctx, model);
44
- clearFailures(state, model.id);
45
- redis.mirrorFailures(model.id, state.models[model.id]);
74
+ clearFailures(state, key);
75
+ redis.mirrorFailures(key, state.models[key]);
46
76
  return result;
47
77
  } catch (error) {
48
78
  errors.push(error);
49
- markFailure(state, model.id, error, options);
50
- redis.mirrorFailure(model.id, state.models[model.id]);
79
+ markFailure(state, key, error, options);
80
+ redis.mirrorFailure(key, state.models[key]);
51
81
  }
52
82
  }
53
83
 
@@ -60,8 +90,9 @@ function createProviderRouter(config = {}) {
60
90
  const stats = {};
61
91
  providers.forEach(provider => {
62
92
  (provider.models || []).forEach(model => {
63
- const modelState = state.models[model.id] || createModelState();
64
- stats[model.id] = {
93
+ const key = modelKey(provider, model);
94
+ const modelState = state.models[key] || createModelState();
95
+ stats[key] = {
65
96
  provider: provider.id,
66
97
  rpm_now: currentRpm(modelState, now),
67
98
  rpm_limit: model.rpm ?? null,
@@ -93,7 +124,7 @@ function createInitialState(providers) {
93
124
  const state = { models: {} };
94
125
  providers.forEach(provider => {
95
126
  (provider.models || []).forEach(model => {
96
- state.models[model.id] = createModelState();
127
+ state.models[modelKey(provider, model)] = createModelState();
97
128
  });
98
129
  });
99
130
  return state;
@@ -110,14 +141,13 @@ function createModelState() {
110
141
  };
111
142
  }
112
143
 
113
- // Redis is a best-effort, optional shared-state layer: if it's absent,
114
- // misconfigured, or fails at any point, the router must keep working with
115
- // its in-memory state only — never let Redis trouble block or crash a call.
144
+ // Redis makes quota reservations atomically across instances. If it is absent
145
+ // or unavailable, the router falls back to the process-local counters.
116
146
  function createRedisLink(config, options) {
117
147
  const noop = {
118
148
  connect: async () => {},
119
149
  restoreState: async () => {},
120
- mirrorUsage: () => {},
150
+ reserveUsage: async () => true,
121
151
  mirrorFailure: () => {},
122
152
  mirrorFailures: () => {},
123
153
  disconnect: () => {}
@@ -127,8 +157,8 @@ function createRedisLink(config, options) {
127
157
 
128
158
  let client = null;
129
159
  const prefix = options.redisKeyPrefix;
130
- const dayKey = (type, modelId) => `${prefix}:${type}:${modelId}:${new Date().toDateString()}`;
131
- const stateKey = (type, modelId) => `${prefix}:${type}:${modelId}`;
160
+ const dayKey = (type, key) => `${prefix}:${type}:${key}:${new Date().toISOString().slice(0, 10)}`;
161
+ const stateKey = (type, key) => `${prefix}:${type}:${key}`;
132
162
  const secondsUntilMidnight = () => Math.ceil(msUntilNextMidnight() / 1000);
133
163
 
134
164
  async function connect() {
@@ -153,13 +183,13 @@ function createRedisLink(config, options) {
153
183
  async function restoreState(state) {
154
184
  if (!client || !client.isOpen) return;
155
185
  try {
156
- for (const [modelId, modelState] of Object.entries(state.models)) {
186
+ for (const [key, modelState] of Object.entries(state.models)) {
157
187
  const [rpd, tpd, failures, cooldownTtl, degradedTtl] = await Promise.all([
158
- client.get(dayKey('rpd', modelId)),
159
- client.get(dayKey('tpd', modelId)),
160
- client.get(stateKey('failures', modelId)),
161
- client.ttl(stateKey('cooldown', modelId)),
162
- client.ttl(stateKey('degraded', modelId))
188
+ client.get(dayKey('rpd', key)),
189
+ client.get(dayKey('tpd', key)),
190
+ client.get(stateKey('failures', key)),
191
+ client.ttl(stateKey('cooldown', key)),
192
+ client.ttl(stateKey('degraded', key))
163
193
  ]);
164
194
 
165
195
  if (rpd) modelState.rpdUsed = parseInt(rpd, 10);
@@ -173,32 +203,49 @@ function createRedisLink(config, options) {
173
203
  }
174
204
  }
175
205
 
176
- function mirrorUsage(modelId, modelState) {
177
- if (!client || !client.isOpen) return;
178
- const ttl = secondsUntilMidnight();
179
- client.incrBy(dayKey('rpd', modelId), 1).catch(() => {});
180
- client.expire(dayKey('rpd', modelId), ttl).catch(() => {});
181
- if (modelState.tpdUsed) {
182
- client.set(dayKey('tpd', modelId), String(modelState.tpdUsed), { EX: ttl }).catch(() => {});
206
+ async function reserveUsage(key, model, request) {
207
+ if (!client || !client.isOpen) return true;
208
+ try {
209
+ const reserved = await client.eval(RESERVE_USAGE_SCRIPT, {
210
+ keys: [
211
+ stateKey('rpm', key),
212
+ dayKey('rpd', key),
213
+ dayKey('tpd', key)
214
+ ],
215
+ arguments: [
216
+ String(Date.now()),
217
+ String(model.rpm || 0),
218
+ String(model.rpd || 0),
219
+ String(model.tpd || 0),
220
+ String(estimatedTokens(request)),
221
+ randomUUID(),
222
+ String(RPM_WINDOW_MS),
223
+ String(Math.ceil(RPM_WINDOW_MS / 1000)),
224
+ String(secondsUntilMidnight())
225
+ ]
226
+ });
227
+ return Number(reserved) === 1;
228
+ } catch (_error) {
229
+ return true;
183
230
  }
184
231
  }
185
232
 
186
- function mirrorFailures(modelId, modelState) {
233
+ function mirrorFailures(key, modelState) {
187
234
  if (!client || !client.isOpen) return;
188
- client.del(stateKey('failures', modelId)).catch(() => {});
189
- if (!modelState.degradedUntil) client.del(stateKey('degraded', modelId)).catch(() => {});
235
+ client.del(stateKey('failures', key)).catch(() => {});
236
+ if (!modelState.degradedUntil) client.del(stateKey('degraded', key)).catch(() => {});
190
237
  }
191
238
 
192
- function mirrorFailure(modelId, modelState) {
239
+ function mirrorFailure(key, modelState) {
193
240
  if (!client || !client.isOpen) return;
194
- client.set(stateKey('failures', modelId), String(modelState.failures), { EX: 86400 }).catch(() => {});
241
+ client.set(stateKey('failures', key), String(modelState.failures), { EX: 86400 }).catch(() => {});
195
242
  if (modelState.cooldownUntil) {
196
243
  const ttl = Math.max(1, Math.ceil((modelState.cooldownUntil - Date.now()) / 1000));
197
- client.set(stateKey('cooldown', modelId), '1', { EX: ttl }).catch(() => {});
244
+ client.set(stateKey('cooldown', key), '1', { EX: ttl }).catch(() => {});
198
245
  }
199
246
  if (modelState.degradedUntil) {
200
247
  const ttl = Math.max(1, Math.ceil((modelState.degradedUntil - Date.now()) / 1000));
201
- client.set(stateKey('degraded', modelId), '1', { EX: ttl }).catch(() => {});
248
+ client.set(stateKey('degraded', key), '1', { EX: ttl }).catch(() => {});
202
249
  }
203
250
  }
204
251
 
@@ -209,7 +256,7 @@ function createRedisLink(config, options) {
209
256
  client = null;
210
257
  }
211
258
 
212
- return { connect, restoreState, mirrorUsage, mirrorFailure, mirrorFailures, disconnect };
259
+ return { connect, restoreState, reserveUsage, mirrorFailure, mirrorFailures, disconnect };
213
260
  }
214
261
 
215
262
  function selectCandidates(providers, intentRouting, request) {
@@ -240,10 +287,10 @@ function supportsComplexity(model, complexity) {
240
287
  return Array.isArray(model.complexity) && model.complexity.includes(complexity);
241
288
  }
242
289
 
243
- function isModelAvailable(state, model, request) {
290
+ function isModelAvailable(state, key, model, request) {
244
291
  const now = Date.now();
245
- const modelState = state.models[model.id] || createModelState();
246
- state.models[model.id] = modelState;
292
+ const modelState = state.models[key] || createModelState();
293
+ state.models[key] = modelState;
247
294
 
248
295
  if (isUntilActive(modelState.cooldownUntil, now)) return false;
249
296
  if (isUntilActive(modelState.degradedUntil, now)) return false;
@@ -253,14 +300,14 @@ function isModelAvailable(state, model, request) {
253
300
  return true;
254
301
  }
255
302
 
256
- function reserveUsage(state, model, request) {
257
- const modelState = state.models[model.id] || createModelState();
303
+ function reserveUsage(state, key, request) {
304
+ const modelState = state.models[key] || createModelState();
258
305
  const now = Date.now();
259
306
  modelState.rpmWindow = modelState.rpmWindow.filter(ts => now - ts < RPM_WINDOW_MS);
260
307
  modelState.rpmWindow.push(now);
261
308
  modelState.rpdUsed += 1;
262
309
  modelState.tpdUsed += estimatedTokens(request);
263
- state.models[model.id] = modelState;
310
+ state.models[key] = modelState;
264
311
  }
265
312
 
266
313
  function estimatedTokens(request) {
@@ -297,6 +344,10 @@ function clearFailures(state, modelId) {
297
344
  state.models[modelId] = modelState;
298
345
  }
299
346
 
347
+ function modelKey(provider, model) {
348
+ return `${provider.id}:${model.id}`;
349
+ }
350
+
300
351
  function isRateLimitError(error) {
301
352
  return error && (
302
353
  error.statusCode === 429 ||