@astratra/ai 0.1.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/LICENSE +21 -0
- package/README.md +96 -0
- package/package.json +43 -0
- package/src/agentLoop.js +100 -0
- package/src/index.d.ts +100 -0
- package/src/index.js +5 -0
- package/src/providerRouter.js +329 -0
- package/src/toolRegistry.js +47 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Astratra
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# @astratra/ai
|
|
2
|
+
|
|
3
|
+
Routing IA multi-provider générique, registre d'outils et une boucle
|
|
4
|
+
d'agent minimale à tool-calling. Dépend de `@astratra/core`.
|
|
5
|
+
|
|
6
|
+
Ce package ne fournit volontairement aucun catalogue de modèles, aucun SDK
|
|
7
|
+
provider, aucun outil métier — tout ça vient du projet consommateur. Ce
|
|
8
|
+
qu'il fournit, c'est le mécanisme durement acquis : suivi de quota, ordre de
|
|
9
|
+
fallback, cooldown/dégradation, et une petite boucle d'orchestration
|
|
10
|
+
d'agent.
|
|
11
|
+
|
|
12
|
+
## Routeur de providers
|
|
13
|
+
|
|
14
|
+
```js
|
|
15
|
+
const { createProviderRouter } = require('@astratra/ai');
|
|
16
|
+
|
|
17
|
+
const router = createProviderRouter({
|
|
18
|
+
redisUrl: process.env.REDIS_URL, // optionnel — état partagé entre instances, repli RAM si absent/injoignable
|
|
19
|
+
intentRouting: {
|
|
20
|
+
summarize: { preferred: ['fast-model'] }
|
|
21
|
+
},
|
|
22
|
+
providers: [
|
|
23
|
+
{
|
|
24
|
+
id: 'mon-provider-llm',
|
|
25
|
+
models: [{ id: 'fast-model', rpm: 30, rpd: 1000, tpd: 200000, complexity: ['simple', 'medium'] }],
|
|
26
|
+
call: async (prompt, ctx, model) => monClient.complete(model.id, prompt)
|
|
27
|
+
}
|
|
28
|
+
]
|
|
29
|
+
});
|
|
30
|
+
|
|
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é
|
|
33
|
+
router.stop(); // arrête le timer de reset minuit et ferme le lien Redis, s'il existe
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Les providers sont essayés dans l'ordre du tableau que vous fournissez —
|
|
37
|
+
l'ordre de fallback est votre décision, pas figé dans le package. Les
|
|
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.
|
|
41
|
+
|
|
42
|
+
## Registre d'outils
|
|
43
|
+
|
|
44
|
+
```js
|
|
45
|
+
const { createToolRegistry } = require('@astratra/ai');
|
|
46
|
+
|
|
47
|
+
const registry = createToolRegistry();
|
|
48
|
+
registry.register({
|
|
49
|
+
name: 'get_patient_record',
|
|
50
|
+
description: "Récupère le dossier d'un patient par son id",
|
|
51
|
+
type: 'read',
|
|
52
|
+
roles: ['doctor', 'admin'],
|
|
53
|
+
params: { patientId: 'string' },
|
|
54
|
+
handler: async ({ patientId }, ctx) => patientStore.findById(patientId)
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Vide par défaut — aucun outil pré-enregistré. `registry.formatToolsForPrompt(role)`
|
|
59
|
+
formate en texte les outils visibles pour un rôle donné, à injecter dans un
|
|
60
|
+
prompt système.
|
|
61
|
+
|
|
62
|
+
## Boucle d'agent (V0)
|
|
63
|
+
|
|
64
|
+
```js
|
|
65
|
+
const { runAgentLoop } = require('@astratra/ai');
|
|
66
|
+
|
|
67
|
+
const reponse = await runAgentLoop({
|
|
68
|
+
prompt: 'Quel est le solde du patient X ?',
|
|
69
|
+
ctx: { tenantId: 'clinic-1' },
|
|
70
|
+
registry,
|
|
71
|
+
router,
|
|
72
|
+
userRole: 'doctor',
|
|
73
|
+
maxSteps: 5
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Parse `<tool_call name="...">{...json...}</tool_call>` dans la réponse du
|
|
78
|
+
modèle, exécute l'outil correspondant enregistré (refuse si le rôle n'y a
|
|
79
|
+
pas accès), réinjecte le résultat sous forme de `<tool_result>`, et boucle
|
|
80
|
+
jusqu'à une réponse finale ou `maxSteps` atteint.
|
|
81
|
+
|
|
82
|
+
**Périmètre V0 — volontairement exclu :** streaming token par token,
|
|
83
|
+
gestion d'images/vision, et confirmation humaine avant l'exécution d'un
|
|
84
|
+
outil sensible. Ce sont de vraies fonctionnalités non triviales dont une
|
|
85
|
+
boucle d'agent de production a besoin, mais les porter fidèlement a été
|
|
86
|
+
jugé trop ambitieux pour cette première version du package. À construire
|
|
87
|
+
dans votre propre boucle, ou à couvrir dans un futur spec.
|
|
88
|
+
|
|
89
|
+
## Tests
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npm test --workspace @astratra/ai
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
12 tests. Providers et Redis sont mockés — aucune vraie clé API ni serveur
|
|
96
|
+
Redis requis.
|
package/package.json
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@astratra/ai",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
|
|
5
|
+
"main": "src/index.js",
|
|
6
|
+
"types": "src/index.d.ts",
|
|
7
|
+
"type": "commonjs",
|
|
8
|
+
"files": [
|
|
9
|
+
"src"
|
|
10
|
+
],
|
|
11
|
+
"scripts": {
|
|
12
|
+
"test": "jest"
|
|
13
|
+
},
|
|
14
|
+
"jest": {
|
|
15
|
+
"testMatch": [
|
|
16
|
+
"**/__tests__/**/*.test.js"
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
"keywords": [
|
|
20
|
+
"astratra",
|
|
21
|
+
"ai",
|
|
22
|
+
"agents"
|
|
23
|
+
],
|
|
24
|
+
"license": "MIT",
|
|
25
|
+
"publishConfig": {
|
|
26
|
+
"access": "public"
|
|
27
|
+
},
|
|
28
|
+
"dependencies": {
|
|
29
|
+
"@astratra/core": "^0.1.0"
|
|
30
|
+
},
|
|
31
|
+
"peerDependencies": {
|
|
32
|
+
"redis": ">=4"
|
|
33
|
+
},
|
|
34
|
+
"peerDependenciesMeta": {
|
|
35
|
+
"redis": {
|
|
36
|
+
"optional": true
|
|
37
|
+
}
|
|
38
|
+
},
|
|
39
|
+
"devDependencies": {
|
|
40
|
+
"jest": "30.4.2",
|
|
41
|
+
"redis": "^4.7.0"
|
|
42
|
+
}
|
|
43
|
+
}
|
package/src/agentLoop.js
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
const { AppError } = require('@astratra/core');
|
|
2
|
+
|
|
3
|
+
const DEFAULT_MAX_STEPS = 5;
|
|
4
|
+
|
|
5
|
+
async function runAgentLoop({
|
|
6
|
+
prompt,
|
|
7
|
+
ctx = {},
|
|
8
|
+
history = [],
|
|
9
|
+
registry,
|
|
10
|
+
router,
|
|
11
|
+
userRole,
|
|
12
|
+
maxSteps = DEFAULT_MAX_STEPS
|
|
13
|
+
}) {
|
|
14
|
+
if (!registry) throw new AppError('agentLoop requires a registry', 500);
|
|
15
|
+
if (!router || typeof router.ask !== 'function') throw new AppError('agentLoop requires a router', 500);
|
|
16
|
+
|
|
17
|
+
const messages = Array.isArray(history) ? [...history] : [];
|
|
18
|
+
messages.push({ role: 'user', content: prompt });
|
|
19
|
+
|
|
20
|
+
for (let step = 0; step < maxSteps; step += 1) {
|
|
21
|
+
const modelPrompt = buildPrompt(registry, userRole, messages);
|
|
22
|
+
const response = await stringifyModelResponse(await router.ask(modelPrompt, {
|
|
23
|
+
complexity: 'agent',
|
|
24
|
+
intent: 'agent_loop',
|
|
25
|
+
estimatedTokens: estimateTokens(modelPrompt)
|
|
26
|
+
}, ctx));
|
|
27
|
+
const toolCall = parseToolCall(response);
|
|
28
|
+
|
|
29
|
+
if (!toolCall) {
|
|
30
|
+
return response;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const tool = registry.getToolByName(toolCall.name);
|
|
34
|
+
if (!tool) {
|
|
35
|
+
throw new AppError(`Tool "${toolCall.name}" is not registered`, 400);
|
|
36
|
+
}
|
|
37
|
+
if (!tool.roles.includes(userRole)) {
|
|
38
|
+
throw new AppError(`Tool "${toolCall.name}" is not allowed for role "${userRole}"`, 403);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const result = await tool.handler(toolCall.params, ctx);
|
|
42
|
+
messages.push({ role: 'assistant', content: response });
|
|
43
|
+
messages.push({
|
|
44
|
+
role: 'tool',
|
|
45
|
+
content: `<tool_result name="${tool.name}">${JSON.stringify(result)}</tool_result>`
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
throw new AppError(`agentLoop reached maxSteps (${maxSteps}) before a final answer`, 500);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function buildPrompt(registry, userRole, messages) {
|
|
53
|
+
const tools = registry.formatToolsForPrompt(userRole);
|
|
54
|
+
const renderedHistory = messages.map(message => {
|
|
55
|
+
if (typeof message === 'string') return message;
|
|
56
|
+
return `${message.role || 'message'}: ${message.content || ''}`;
|
|
57
|
+
}).join('\n');
|
|
58
|
+
|
|
59
|
+
return [
|
|
60
|
+
tools ? `Available tools:\n${tools}` : 'Available tools:\n(none)',
|
|
61
|
+
renderedHistory
|
|
62
|
+
].filter(Boolean).join('\n\n');
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function parseToolCall(text) {
|
|
66
|
+
const match = String(text || '').match(/<tool_call\s+name="([^"]+)">\s*([\s\S]*?)\s*<\/tool_call>/i);
|
|
67
|
+
if (!match) return null;
|
|
68
|
+
|
|
69
|
+
try {
|
|
70
|
+
return {
|
|
71
|
+
name: match[1],
|
|
72
|
+
params: match[2] ? JSON.parse(match[2]) : {}
|
|
73
|
+
};
|
|
74
|
+
} catch (error) {
|
|
75
|
+
throw new AppError(`Invalid JSON params for tool "${match[1]}": ${error.message}`, 400);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
async function stringifyModelResponse(value) {
|
|
80
|
+
if (isAsyncIterable(value)) {
|
|
81
|
+
let output = '';
|
|
82
|
+
for await (const chunk of value) {
|
|
83
|
+
output += String(chunk);
|
|
84
|
+
}
|
|
85
|
+
return output;
|
|
86
|
+
}
|
|
87
|
+
return String(value ?? '');
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function isAsyncIterable(value) {
|
|
91
|
+
return value && typeof value[Symbol.asyncIterator] === 'function';
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function estimateTokens(text) {
|
|
95
|
+
return Math.ceil(String(text || '').length / 4);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
module.exports = {
|
|
99
|
+
runAgentLoop
|
|
100
|
+
};
|
package/src/index.d.ts
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
export type Awaitable<T> = T | Promise<T>;
|
|
2
|
+
|
|
3
|
+
export interface ProviderModel {
|
|
4
|
+
id: string;
|
|
5
|
+
rpm?: number;
|
|
6
|
+
rpd?: number;
|
|
7
|
+
tpd?: number;
|
|
8
|
+
complexity?: string[];
|
|
9
|
+
[key: string]: unknown;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export interface Provider {
|
|
13
|
+
id: string;
|
|
14
|
+
models: ProviderModel[];
|
|
15
|
+
call(prompt: string, ctx: Record<string, unknown>, model: ProviderModel): Awaitable<unknown>;
|
|
16
|
+
[key: string]: unknown;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export interface ProviderRequest {
|
|
20
|
+
complexity?: string;
|
|
21
|
+
estimatedTokens?: number;
|
|
22
|
+
intent?: string;
|
|
23
|
+
maxTokens?: number;
|
|
24
|
+
[key: string]: unknown;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface ProviderRouterConfig {
|
|
28
|
+
providers?: Provider[];
|
|
29
|
+
cooldownMs?: number;
|
|
30
|
+
cooldownJitterMs?: number;
|
|
31
|
+
maxFailures?: number;
|
|
32
|
+
degradedMs?: number;
|
|
33
|
+
intentRouting?: Record<string, { preferred?: string[] }>;
|
|
34
|
+
redisKeyPrefix?: string;
|
|
35
|
+
redisUrl?: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface ProviderStats {
|
|
39
|
+
provider: string;
|
|
40
|
+
rpm_now: number;
|
|
41
|
+
rpm_limit: number | null;
|
|
42
|
+
rpd_used: number;
|
|
43
|
+
rpd_limit: number | null;
|
|
44
|
+
tpd_used: number;
|
|
45
|
+
tpd_limit: number | null;
|
|
46
|
+
cooldown: boolean;
|
|
47
|
+
degraded: boolean;
|
|
48
|
+
failures: number;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface ProviderRouter {
|
|
52
|
+
ask(prompt: string, request?: ProviderRequest, ctx?: Record<string, unknown>): Promise<unknown>;
|
|
53
|
+
getStats(): Record<string, ProviderStats>;
|
|
54
|
+
stop(): void;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function createProviderRouter(config?: ProviderRouterConfig): ProviderRouter;
|
|
58
|
+
|
|
59
|
+
export interface ToolDefinition<TParams = Record<string, unknown>, TResult = unknown> {
|
|
60
|
+
name: string;
|
|
61
|
+
description: string;
|
|
62
|
+
type: string;
|
|
63
|
+
roles: string[];
|
|
64
|
+
params?: Record<string, unknown>;
|
|
65
|
+
handler(params: TParams, ctx: Record<string, unknown>): Awaitable<TResult>;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export interface RegisteredTool<TParams = Record<string, unknown>, TResult = unknown> extends ToolDefinition<TParams, TResult> {
|
|
69
|
+
params: Record<string, unknown>;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export interface ToolRegistry {
|
|
73
|
+
register<TParams = Record<string, unknown>, TResult = unknown>(tool: ToolDefinition<TParams, TResult>): ToolDefinition<TParams, TResult>;
|
|
74
|
+
getToolsForRole(role: string): RegisteredTool[];
|
|
75
|
+
getToolByName(name: string): RegisteredTool | null;
|
|
76
|
+
formatToolsForPrompt(role: string): string;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function createToolRegistry(): ToolRegistry;
|
|
80
|
+
|
|
81
|
+
export interface AgentMessage {
|
|
82
|
+
role?: string;
|
|
83
|
+
content?: string;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export interface AgentRouter {
|
|
87
|
+
ask(prompt: string, request?: ProviderRequest, ctx?: Record<string, unknown>): Awaitable<string | AsyncIterable<unknown> | null | undefined>;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
export interface AgentLoopOptions {
|
|
91
|
+
prompt: string;
|
|
92
|
+
ctx?: Record<string, unknown>;
|
|
93
|
+
history?: Array<string | AgentMessage>;
|
|
94
|
+
registry: ToolRegistry;
|
|
95
|
+
router: AgentRouter;
|
|
96
|
+
userRole: string;
|
|
97
|
+
maxSteps?: number;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export function runAgentLoop(options: AgentLoopOptions): Promise<string>;
|
package/src/index.js
ADDED
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
const { AppError } = require('@astratra/core');
|
|
2
|
+
|
|
3
|
+
const DEFAULT_COOLDOWN_MS = 60 * 1000;
|
|
4
|
+
const DEFAULT_COOLDOWN_JITTER_MS = 8 * 1000;
|
|
5
|
+
const DEFAULT_MAX_FAILURES = 3;
|
|
6
|
+
const DEFAULT_DEGRADED_MS = 5 * 60 * 1000;
|
|
7
|
+
const RPM_WINDOW_MS = 60 * 1000;
|
|
8
|
+
|
|
9
|
+
function createProviderRouter(config = {}) {
|
|
10
|
+
const providers = Array.isArray(config.providers) ? config.providers : [];
|
|
11
|
+
const state = createInitialState(providers);
|
|
12
|
+
const options = {
|
|
13
|
+
cooldownMs: config.cooldownMs ?? DEFAULT_COOLDOWN_MS,
|
|
14
|
+
cooldownJitterMs: config.cooldownJitterMs ?? DEFAULT_COOLDOWN_JITTER_MS,
|
|
15
|
+
maxFailures: config.maxFailures ?? DEFAULT_MAX_FAILURES,
|
|
16
|
+
degradedMs: config.degradedMs ?? DEFAULT_DEGRADED_MS,
|
|
17
|
+
intentRouting: config.intentRouting || {},
|
|
18
|
+
redisKeyPrefix: config.redisKeyPrefix || 'astratra:ai:provider'
|
|
19
|
+
};
|
|
20
|
+
let midnightTimer = null;
|
|
21
|
+
const resetDailyAtMidnight = () => {
|
|
22
|
+
resetDailyUsage(state);
|
|
23
|
+
midnightTimer = setTimeout(resetDailyAtMidnight, msUntilNextMidnight());
|
|
24
|
+
};
|
|
25
|
+
midnightTimer = setTimeout(resetDailyAtMidnight, msUntilNextMidnight());
|
|
26
|
+
|
|
27
|
+
const redis = createRedisLink(config, options);
|
|
28
|
+
const redisReady = redis.connect().then(() => redis.restoreState(state)).catch(() => {});
|
|
29
|
+
|
|
30
|
+
async function ask(prompt, request = {}, ctx = {}) {
|
|
31
|
+
await redisReady;
|
|
32
|
+
const candidates = selectCandidates(providers, options.intentRouting, request);
|
|
33
|
+
const errors = [];
|
|
34
|
+
|
|
35
|
+
for (const candidate of candidates) {
|
|
36
|
+
const { provider, model } = candidate;
|
|
37
|
+
if (!isModelAvailable(state, model, request)) continue;
|
|
38
|
+
|
|
39
|
+
reserveUsage(state, model, request);
|
|
40
|
+
redis.mirrorUsage(model.id, state.models[model.id]);
|
|
41
|
+
|
|
42
|
+
try {
|
|
43
|
+
const result = await provider.call(prompt, ctx, model);
|
|
44
|
+
clearFailures(state, model.id);
|
|
45
|
+
redis.mirrorFailures(model.id, state.models[model.id]);
|
|
46
|
+
return result;
|
|
47
|
+
} catch (error) {
|
|
48
|
+
errors.push(error);
|
|
49
|
+
markFailure(state, model.id, error, options);
|
|
50
|
+
redis.mirrorFailure(model.id, state.models[model.id]);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const suffix = errors.length ? ` Last error: ${errors[errors.length - 1].message}` : '';
|
|
55
|
+
throw new AppError(`No available AI provider/model for this request.${suffix}`, 503);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function getStats() {
|
|
59
|
+
const now = Date.now();
|
|
60
|
+
const stats = {};
|
|
61
|
+
providers.forEach(provider => {
|
|
62
|
+
(provider.models || []).forEach(model => {
|
|
63
|
+
const modelState = state.models[model.id] || createModelState();
|
|
64
|
+
stats[model.id] = {
|
|
65
|
+
provider: provider.id,
|
|
66
|
+
rpm_now: currentRpm(modelState, now),
|
|
67
|
+
rpm_limit: model.rpm ?? null,
|
|
68
|
+
rpd_used: modelState.rpdUsed,
|
|
69
|
+
rpd_limit: model.rpd ?? null,
|
|
70
|
+
tpd_used: modelState.tpdUsed,
|
|
71
|
+
tpd_limit: model.tpd ?? null,
|
|
72
|
+
cooldown: isUntilActive(modelState.cooldownUntil, now),
|
|
73
|
+
degraded: isUntilActive(modelState.degradedUntil, now),
|
|
74
|
+
failures: modelState.failures || 0
|
|
75
|
+
};
|
|
76
|
+
});
|
|
77
|
+
});
|
|
78
|
+
return stats;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function stop() {
|
|
82
|
+
if (midnightTimer) {
|
|
83
|
+
clearTimeout(midnightTimer);
|
|
84
|
+
midnightTimer = null;
|
|
85
|
+
}
|
|
86
|
+
redis.disconnect();
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
return { ask, getStats, stop };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function createInitialState(providers) {
|
|
93
|
+
const state = { models: {} };
|
|
94
|
+
providers.forEach(provider => {
|
|
95
|
+
(provider.models || []).forEach(model => {
|
|
96
|
+
state.models[model.id] = createModelState();
|
|
97
|
+
});
|
|
98
|
+
});
|
|
99
|
+
return state;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function createModelState() {
|
|
103
|
+
return {
|
|
104
|
+
rpmWindow: [],
|
|
105
|
+
rpdUsed: 0,
|
|
106
|
+
tpdUsed: 0,
|
|
107
|
+
cooldownUntil: 0,
|
|
108
|
+
degradedUntil: 0,
|
|
109
|
+
failures: 0
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
|
|
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.
|
|
116
|
+
function createRedisLink(config, options) {
|
|
117
|
+
const noop = {
|
|
118
|
+
connect: async () => {},
|
|
119
|
+
restoreState: async () => {},
|
|
120
|
+
mirrorUsage: () => {},
|
|
121
|
+
mirrorFailure: () => {},
|
|
122
|
+
mirrorFailures: () => {},
|
|
123
|
+
disconnect: () => {}
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
if (!config.redisUrl) return noop;
|
|
127
|
+
|
|
128
|
+
let client = null;
|
|
129
|
+
const prefix = options.redisKeyPrefix;
|
|
130
|
+
const dayKey = (type, modelId) => `${prefix}:${type}:${modelId}:${new Date().toDateString()}`;
|
|
131
|
+
const stateKey = (type, modelId) => `${prefix}:${type}:${modelId}`;
|
|
132
|
+
const secondsUntilMidnight = () => Math.ceil(msUntilNextMidnight() / 1000);
|
|
133
|
+
|
|
134
|
+
async function connect() {
|
|
135
|
+
let RedisModule;
|
|
136
|
+
try {
|
|
137
|
+
RedisModule = require('redis');
|
|
138
|
+
} catch (_error) {
|
|
139
|
+
return;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
try {
|
|
143
|
+
client = RedisModule.createClient({ url: config.redisUrl });
|
|
144
|
+
client.on('error', () => {
|
|
145
|
+
// Swallow: a Redis outage must never surface as an app-level error.
|
|
146
|
+
});
|
|
147
|
+
await client.connect();
|
|
148
|
+
} catch (_error) {
|
|
149
|
+
client = null;
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
async function restoreState(state) {
|
|
154
|
+
if (!client || !client.isOpen) return;
|
|
155
|
+
try {
|
|
156
|
+
for (const [modelId, modelState] of Object.entries(state.models)) {
|
|
157
|
+
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))
|
|
163
|
+
]);
|
|
164
|
+
|
|
165
|
+
if (rpd) modelState.rpdUsed = parseInt(rpd, 10);
|
|
166
|
+
if (tpd) modelState.tpdUsed = parseInt(tpd, 10);
|
|
167
|
+
if (failures) modelState.failures = parseInt(failures, 10);
|
|
168
|
+
if (cooldownTtl > 0) modelState.cooldownUntil = Date.now() + cooldownTtl * 1000;
|
|
169
|
+
if (degradedTtl > 0) modelState.degradedUntil = Date.now() + degradedTtl * 1000;
|
|
170
|
+
}
|
|
171
|
+
} catch (_error) {
|
|
172
|
+
// Partial or failed restore just means we start from RAM defaults.
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
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(() => {});
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function mirrorFailures(modelId, modelState) {
|
|
187
|
+
if (!client || !client.isOpen) return;
|
|
188
|
+
client.del(stateKey('failures', modelId)).catch(() => {});
|
|
189
|
+
if (!modelState.degradedUntil) client.del(stateKey('degraded', modelId)).catch(() => {});
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
function mirrorFailure(modelId, modelState) {
|
|
193
|
+
if (!client || !client.isOpen) return;
|
|
194
|
+
client.set(stateKey('failures', modelId), String(modelState.failures), { EX: 86400 }).catch(() => {});
|
|
195
|
+
if (modelState.cooldownUntil) {
|
|
196
|
+
const ttl = Math.max(1, Math.ceil((modelState.cooldownUntil - Date.now()) / 1000));
|
|
197
|
+
client.set(stateKey('cooldown', modelId), '1', { EX: ttl }).catch(() => {});
|
|
198
|
+
}
|
|
199
|
+
if (modelState.degradedUntil) {
|
|
200
|
+
const ttl = Math.max(1, Math.ceil((modelState.degradedUntil - Date.now()) / 1000));
|
|
201
|
+
client.set(stateKey('degraded', modelId), '1', { EX: ttl }).catch(() => {});
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
function disconnect() {
|
|
206
|
+
if (client && client.isOpen) {
|
|
207
|
+
client.disconnect().catch(() => {});
|
|
208
|
+
}
|
|
209
|
+
client = null;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
return { connect, restoreState, mirrorUsage, mirrorFailure, mirrorFailures, disconnect };
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function selectCandidates(providers, intentRouting, request) {
|
|
216
|
+
const preferred = request.intent && intentRouting[request.intent]
|
|
217
|
+
? intentRouting[request.intent].preferred || []
|
|
218
|
+
: [];
|
|
219
|
+
const candidates = [];
|
|
220
|
+
|
|
221
|
+
providers.forEach(provider => {
|
|
222
|
+
const models = provider.models || [];
|
|
223
|
+
const preferredModels = preferred
|
|
224
|
+
.map(id => models.find(model => model.id === id))
|
|
225
|
+
.filter(Boolean);
|
|
226
|
+
const otherModels = models.filter(model => !preferred.includes(model.id));
|
|
227
|
+
|
|
228
|
+
[...preferredModels, ...otherModels].forEach(model => {
|
|
229
|
+
if (supportsComplexity(model, request.complexity)) {
|
|
230
|
+
candidates.push({ provider, model });
|
|
231
|
+
}
|
|
232
|
+
});
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
return candidates;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
function supportsComplexity(model, complexity) {
|
|
239
|
+
if (!complexity) return true;
|
|
240
|
+
return Array.isArray(model.complexity) && model.complexity.includes(complexity);
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
function isModelAvailable(state, model, request) {
|
|
244
|
+
const now = Date.now();
|
|
245
|
+
const modelState = state.models[model.id] || createModelState();
|
|
246
|
+
state.models[model.id] = modelState;
|
|
247
|
+
|
|
248
|
+
if (isUntilActive(modelState.cooldownUntil, now)) return false;
|
|
249
|
+
if (isUntilActive(modelState.degradedUntil, now)) return false;
|
|
250
|
+
if (model.rpm && currentRpm(modelState, now) >= model.rpm) return false;
|
|
251
|
+
if (model.rpd && modelState.rpdUsed >= model.rpd) return false;
|
|
252
|
+
if (model.tpd && modelState.tpdUsed + estimatedTokens(request) > model.tpd) return false;
|
|
253
|
+
return true;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function reserveUsage(state, model, request) {
|
|
257
|
+
const modelState = state.models[model.id] || createModelState();
|
|
258
|
+
const now = Date.now();
|
|
259
|
+
modelState.rpmWindow = modelState.rpmWindow.filter(ts => now - ts < RPM_WINDOW_MS);
|
|
260
|
+
modelState.rpmWindow.push(now);
|
|
261
|
+
modelState.rpdUsed += 1;
|
|
262
|
+
modelState.tpdUsed += estimatedTokens(request);
|
|
263
|
+
state.models[model.id] = modelState;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
function estimatedTokens(request) {
|
|
267
|
+
return Math.max(0, Number(request.estimatedTokens || request.maxTokens || 0));
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
function currentRpm(modelState, now) {
|
|
271
|
+
modelState.rpmWindow = modelState.rpmWindow.filter(ts => now - ts < RPM_WINDOW_MS);
|
|
272
|
+
return modelState.rpmWindow.length;
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
function isUntilActive(until, now) {
|
|
276
|
+
return Boolean(until && until > now);
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
function markFailure(state, modelId, error, options) {
|
|
280
|
+
const modelState = state.models[modelId] || createModelState();
|
|
281
|
+
modelState.failures = (modelState.failures || 0) + 1;
|
|
282
|
+
|
|
283
|
+
if (isRateLimitError(error)) {
|
|
284
|
+
modelState.cooldownUntil = Date.now() + options.cooldownMs + jitter(options.cooldownJitterMs);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
if (modelState.failures >= options.maxFailures) {
|
|
288
|
+
modelState.degradedUntil = Date.now() + options.degradedMs;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
state.models[modelId] = modelState;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
function clearFailures(state, modelId) {
|
|
295
|
+
const modelState = state.models[modelId] || createModelState();
|
|
296
|
+
modelState.failures = 0;
|
|
297
|
+
state.models[modelId] = modelState;
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
function isRateLimitError(error) {
|
|
301
|
+
return error && (
|
|
302
|
+
error.statusCode === 429 ||
|
|
303
|
+
error.status === 429 ||
|
|
304
|
+
error.code === 429 ||
|
|
305
|
+
error.code === '429'
|
|
306
|
+
);
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
function jitter(maxMs) {
|
|
310
|
+
if (!maxMs) return 0;
|
|
311
|
+
return Math.floor(Math.random() * maxMs);
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
function msUntilNextMidnight(now = new Date()) {
|
|
315
|
+
const next = new Date(now);
|
|
316
|
+
next.setHours(24, 0, 0, 0);
|
|
317
|
+
return Math.max(1, next.getTime() - now.getTime());
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
function resetDailyUsage(state) {
|
|
321
|
+
Object.values(state.models).forEach(modelState => {
|
|
322
|
+
modelState.rpdUsed = 0;
|
|
323
|
+
modelState.tpdUsed = 0;
|
|
324
|
+
});
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
module.exports = {
|
|
328
|
+
createProviderRouter
|
|
329
|
+
};
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
function createToolRegistry() {
|
|
2
|
+
const tools = [];
|
|
3
|
+
|
|
4
|
+
function register(tool) {
|
|
5
|
+
validateTool(tool);
|
|
6
|
+
tools.push({ ...tool, roles: [...tool.roles], params: tool.params || {} });
|
|
7
|
+
return tool;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
function getToolsForRole(role) {
|
|
11
|
+
return tools.filter(tool => tool.roles.includes(role));
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
function getToolByName(name) {
|
|
15
|
+
return tools.find(tool => tool.name === name) || null;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function formatToolsForPrompt(role) {
|
|
19
|
+
return getToolsForRole(role).map(tool => {
|
|
20
|
+
const params = Object.entries(tool.params || {})
|
|
21
|
+
.map(([key, value]) => ` - ${key}: ${value}`)
|
|
22
|
+
.join('\n') || ' (aucun paramètre)';
|
|
23
|
+
|
|
24
|
+
return `### ${tool.name} [${String(tool.type).toUpperCase()}]\n${tool.description}\nParamètres:\n${params}`;
|
|
25
|
+
}).join('\n\n');
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
return {
|
|
29
|
+
register,
|
|
30
|
+
getToolsForRole,
|
|
31
|
+
getToolByName,
|
|
32
|
+
formatToolsForPrompt
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function validateTool(tool) {
|
|
37
|
+
if (!tool || typeof tool !== 'object') throw new Error('tool must be an object');
|
|
38
|
+
if (!tool.name) throw new Error('tool.name is required');
|
|
39
|
+
if (!tool.description) throw new Error('tool.description is required');
|
|
40
|
+
if (!tool.type) throw new Error('tool.type is required');
|
|
41
|
+
if (!Array.isArray(tool.roles)) throw new Error('tool.roles must be an array');
|
|
42
|
+
if (typeof tool.handler !== 'function') throw new Error('tool.handler must be a function');
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
module.exports = {
|
|
46
|
+
createToolRegistry
|
|
47
|
+
};
|