@astratra/ai 0.1.0 → 1.0.1
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 +9 -8
- package/package.json +2 -2
- package/src/index.d.ts +1 -0
- package/src/providerRouter.js +94 -43
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 —
|
|
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
|
|
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
|
|
40
|
-
|
|
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
|
|
|
@@ -59,7 +63,7 @@ Vide par défaut — aucun outil pré-enregistré. `registry.formatToolsForPromp
|
|
|
59
63
|
formate en texte les outils visibles pour un rôle donné, à injecter dans un
|
|
60
64
|
prompt système.
|
|
61
65
|
|
|
62
|
-
## Boucle d'agent
|
|
66
|
+
## Boucle d'agent
|
|
63
67
|
|
|
64
68
|
```js
|
|
65
69
|
const { runAgentLoop } = require('@astratra/ai');
|
|
@@ -91,6 +95,3 @@ dans votre propre boucle, ou à couvrir dans un futur spec.
|
|
|
91
95
|
```bash
|
|
92
96
|
npm test --workspace @astratra/ai
|
|
93
97
|
```
|
|
94
|
-
|
|
95
|
-
12 tests. Providers et Redis sont mockés — aucune vraie clé API ni serveur
|
|
96
|
-
Redis requis.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/ai",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
|
|
5
5
|
"main": "src/index.js",
|
|
6
6
|
"types": "src/index.d.ts",
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"access": "public"
|
|
27
27
|
},
|
|
28
28
|
"dependencies": {
|
|
29
|
-
"@astratra/core": "^
|
|
29
|
+
"@astratra/core": "^1.0.0"
|
|
30
30
|
},
|
|
31
31
|
"peerDependencies": {
|
|
32
32
|
"redis": ">=4"
|
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
|
}
|
package/src/providerRouter.js
CHANGED
|
@@ -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
|
-
|
|
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,
|
|
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,
|
|
45
|
-
redis.mirrorFailures(
|
|
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,
|
|
50
|
-
redis.mirrorFailure(
|
|
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
|
|
64
|
-
|
|
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
|
|
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
|
|
114
|
-
//
|
|
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
|
-
|
|
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,
|
|
131
|
-
const stateKey = (type,
|
|
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 [
|
|
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',
|
|
159
|
-
client.get(dayKey('tpd',
|
|
160
|
-
client.get(stateKey('failures',
|
|
161
|
-
client.ttl(stateKey('cooldown',
|
|
162
|
-
client.ttl(stateKey('degraded',
|
|
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
|
|
177
|
-
if (!client || !client.isOpen) return;
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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(
|
|
233
|
+
function mirrorFailures(key, modelState) {
|
|
187
234
|
if (!client || !client.isOpen) return;
|
|
188
|
-
client.del(stateKey('failures',
|
|
189
|
-
if (!modelState.degradedUntil) client.del(stateKey('degraded',
|
|
235
|
+
client.del(stateKey('failures', key)).catch(() => {});
|
|
236
|
+
if (!modelState.degradedUntil) client.del(stateKey('degraded', key)).catch(() => {});
|
|
190
237
|
}
|
|
191
238
|
|
|
192
|
-
function mirrorFailure(
|
|
239
|
+
function mirrorFailure(key, modelState) {
|
|
193
240
|
if (!client || !client.isOpen) return;
|
|
194
|
-
client.set(stateKey('failures',
|
|
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',
|
|
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',
|
|
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,
|
|
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[
|
|
246
|
-
state.models[
|
|
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,
|
|
257
|
-
const modelState = state.models[
|
|
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[
|
|
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 ||
|