@astratra/ai 1.3.0 → 1.5.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/README.md +262 -2
- package/package.json +2 -1
- package/src/agentLoop.js +88 -11
- package/src/answerText.js +137 -0
- package/src/askLimit.js +73 -0
- package/src/breakers.js +97 -0
- package/src/eventStream.js +47 -0
- package/src/gemini.js +152 -0
- package/src/index.d.ts +452 -3
- package/src/index.js +13 -1
- package/src/language.js +85 -0
- package/src/masking.js +279 -0
- package/src/modelAnswers.js +119 -0
- package/src/nativeTools.js +256 -0
- package/src/openaiCompatible.js +158 -0
- package/src/passages.js +101 -0
- package/src/providerRouter.js +224 -44
- package/src/sources.js +243 -0
- package/src/webSearch.js +71 -0
package/README.md
CHANGED
|
@@ -6,8 +6,9 @@ d'agent minimale à tool-calling. Dépend de `@astratra/core`.
|
|
|
6
6
|
Ce package ne fournit volontairement aucun catalogue de modèles, aucun SDK
|
|
7
7
|
provider, aucun outil métier — tout ça vient du projet consommateur. Ce
|
|
8
8
|
qu'il fournit, c'est le mécanisme durement acquis : suivi de quota, ordre de
|
|
9
|
-
fallback, cooldown/dégradation,
|
|
10
|
-
d'agent
|
|
9
|
+
fallback, cooldown/dégradation, deux adaptateurs HTTP sans dépendance (le
|
|
10
|
+
format OpenAI et Gemini), et deux boucles d'agent (protocole écrit, ou
|
|
11
|
+
appels d'outils natifs).
|
|
11
12
|
|
|
12
13
|
## Routeur de providers
|
|
13
14
|
|
|
@@ -43,6 +44,129 @@ continue avec des compteurs RAM locaux : ce repli ne peut pas garantir un
|
|
|
43
44
|
quota distribué. Les compteurs journaliers se réinitialisent automatiquement
|
|
44
45
|
à minuit.
|
|
45
46
|
|
|
47
|
+
### L'ordre d'une demande, et qui a répondu
|
|
48
|
+
|
|
49
|
+
Un même projet a souvent plusieurs ordres pour les mêmes modèles : le plus
|
|
50
|
+
rapide d'abord pour ce que la personne attend, le plus capable d'abord pour
|
|
51
|
+
le reste, ceux qui voient seulement pour une photo. `route` dit en plus qui a
|
|
52
|
+
répondu (pour les journaux).
|
|
53
|
+
|
|
54
|
+
```js
|
|
55
|
+
const router = createProviderRouter({
|
|
56
|
+
providers,
|
|
57
|
+
cooldownMs: 120_000,
|
|
58
|
+
cooldownJitterMs: 0,
|
|
59
|
+
// Ce qui met au repos : un 429 par défaut ; ici aussi un 503 et un délai dépassé.
|
|
60
|
+
cooldownOn: (error) => [429, 503].includes(error.statusCode) || error.name === 'TimeoutError',
|
|
61
|
+
// Tous au repos ? On les essaie quand même : un repos est une supposition.
|
|
62
|
+
whenAllCooling: 'try'
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
const { value, key, partial } = await router.route(requete, {
|
|
66
|
+
candidates: [{ provider: 'groq', model: 'qwen/qwen3.8-27b', extra: { reasoning_format: 'hidden' } }, { provider: 'gemini', model: 'gemini-3.6-flash' }],
|
|
67
|
+
select: (model, provider) => provider.id === 'gemini' || model.vision === true, // une photo : ceux qui voient
|
|
68
|
+
accepts: (reponse) => Boolean(reponse.text), // refusée : le suivant
|
|
69
|
+
partial: (reponse) => reponse.cut === true // coupée : en dernier recours
|
|
70
|
+
}, { signal, purpose: 'chat' });
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- Un fournisseur dont `available(ctx)` est faux (pas de clé) est sauté sans
|
|
74
|
+
bruit ; aucun disponible : `code: 'AI_NO_PROVIDER'`. Aucun qui convienne à
|
|
75
|
+
`select` : `'AI_NO_MATCH'`. Tous essayés : `'AI_UNAVAILABLE'` (AppError 503).
|
|
76
|
+
- Une réponse refusée par `accepts` passe au modèle suivant sans compter comme
|
|
77
|
+
une panne ; une réponse `partial` n'est rendue que si personne ne finit.
|
|
78
|
+
- Une **voie** (`provider.lane(ctx)`) : une clé à part pour un usage, avec son
|
|
79
|
+
propre quota. Elle se repose seule (`"gemini:modèle@news"`) : une clé saturée
|
|
80
|
+
par un travail de fond n'arrête jamais les conversations.
|
|
81
|
+
- `ctx.signal` interrompu : la demande s'arrête net avec la raison de
|
|
82
|
+
l'appelant, aucun modèle suivant n'est demandé et aucun ne se repose.
|
|
83
|
+
- `now` injecte l'horloge des repos ; `reset()` les oublie. Le minuteur de
|
|
84
|
+
minuit ne garde jamais le processus en vie.
|
|
85
|
+
|
|
86
|
+
### Les adaptateurs : format OpenAI et Gemini
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
const { createGeminiProvider, createOpenAICompatibleProvider } = require('@astratra/ai');
|
|
90
|
+
|
|
91
|
+
createGeminiProvider({
|
|
92
|
+
getKey: (ctx) => ctx.env[`GEMINI_API_KEY_${ctx.purpose}`] || ctx.env.GEMINI_API_KEY,
|
|
93
|
+
lane: (ctx) => (ctx.env[`GEMINI_API_KEY_${ctx.purpose}`] ? ctx.purpose : null),
|
|
94
|
+
fetch, detailed: true, toRequest: (requete) => requete
|
|
95
|
+
});
|
|
96
|
+
createOpenAICompatibleProvider({
|
|
97
|
+
id: 'cloudflare',
|
|
98
|
+
url: (ctx) => ctx.env.CF_ACCOUNT && `https://api.cloudflare.com/client/v4/accounts/${ctx.env.CF_ACCOUNT}/ai/v1/chat/completions`,
|
|
99
|
+
getKey: (ctx) => ctx.env.CF_TOKEN, fetch, detailed: true, toRequest: (requete) => requete
|
|
100
|
+
});
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Les deux prennent la même requête (`{ system, messages, tools, maxTokens }`,
|
|
104
|
+
photos comprises) et rendent la même réponse : `detailed: true` rend
|
|
105
|
+
`{ text, toolCalls, cut }` au routeur, qui juge. La clé et l'adresse sont
|
|
106
|
+
relues à chaque appel (`ctx`) ; `ctx.fetch` et `ctx.timeoutMs` valent pour un
|
|
107
|
+
appel ; `extra` d'un modèle s'ajoute à celui du fournisseur. Gemma reçoit la
|
|
108
|
+
consigne en tête du premier message ; les parties de réflexion et les balises
|
|
109
|
+
`<think>` (même fermée sans ouverture) ne sont jamais montrées ; un appel
|
|
110
|
+
d'outil **écrit dans le texte** (façons de Qwen et de Hermes) devient un vrai
|
|
111
|
+
appel — et n'est jamais une réponse à montrer. Des arguments illisibles gardent
|
|
112
|
+
l'appel, marqué `invalid` avec `invalidReason` (`not_json`, `not_object`), et
|
|
113
|
+
repartent en `{}` au tour suivant.
|
|
114
|
+
|
|
115
|
+
## Outils natifs : la boucle d'un agent qui appelle ses outils
|
|
116
|
+
|
|
117
|
+
```js
|
|
118
|
+
const { createToolCaller, runToolLoop, toolSpecs, validateNativeTools } = require('@astratra/ai');
|
|
119
|
+
|
|
120
|
+
const outils = validateNativeTools(catalogue, { requireSummary: true }); // au démarrage
|
|
121
|
+
const appeler = createToolCaller({
|
|
122
|
+
tools: outils, context: { userId }, signal, timeoutMs: 20_000,
|
|
123
|
+
emit: flux.send, // 'step' { id, tool, params } puis 'step_done' { id, ok }
|
|
124
|
+
keep: sources.keep, // createSourceLedger()
|
|
125
|
+
record: async ({ tool, args, found }) => garderAction(tool, args, found), // à confirmer, à annuler
|
|
126
|
+
messages: { waiting: 'Rien n’est écrit : la personne doit confirmer sur son téléphone.' }
|
|
127
|
+
});
|
|
128
|
+
const { text } = await runToolLoop({
|
|
129
|
+
system, messages, tools: toolSpecs(outils), turn, callTool: appeler,
|
|
130
|
+
maxTurns: 6, maxMs: 60_000, finalInstruction: 'Answer now with what you have read: no more tools.', signal
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Un outil : `{ name, description, parameters, kind, summary?, run }`, avec
|
|
135
|
+
`perform` pour un outil `confirm` (rien n'est écrit avant qu'un humain
|
|
136
|
+
confirme ; le modèle lit que ça attend) et `undo` pour un outil `write`. Un
|
|
137
|
+
outil qui lève, qui tarde, qu'on invente, ou des arguments illisibles
|
|
138
|
+
deviennent une erreur que le modèle **lit** et corrige au tour suivant ; ce
|
|
139
|
+
qu'un outil rend est borné (`resultMax`, 6 000). Les outils demandés ensemble
|
|
140
|
+
tournent en même temps. À court de tours ou de temps, un dernier tour sans
|
|
141
|
+
outils répond avec ce qui a été lu ; un tour sans texte ni outil lève
|
|
142
|
+
`code: 'AI_NO_ANSWER'`, pour que l'appelant réponde autrement.
|
|
143
|
+
`summary(args)` donne les valeurs de la ligne d'étape (`stepParams`, coupées à
|
|
144
|
+
120 caractères) : l'interface écrit la phrase, le serveur n'en écrit aucune.
|
|
145
|
+
|
|
146
|
+
## Le flux vers l'app (server-sent events)
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
const flux = openEventStream(res); // Node ou Express
|
|
150
|
+
flux.send('step', { id: 's1', tool: 'read_bible' });
|
|
151
|
+
flux.close();
|
|
152
|
+
flux.signal; // interrompu quand la personne part — pas quand le serveur ferme
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Chaque bloc s'écrit `event: <type>\ndata: <json>\n\n`, sans mise en tampon par
|
|
156
|
+
un proxy (`X-Accel-Buffering: no`) ; écrire après la fin ne fait rien.
|
|
157
|
+
|
|
158
|
+
## Recherche web (Serper)
|
|
159
|
+
|
|
160
|
+
```js
|
|
161
|
+
const resultats = await searchSerper({ query, sites: ['jw.org'], hl: 'fr' }, {
|
|
162
|
+
key: process.env.SERPER_API_KEY, fetch,
|
|
163
|
+
accept: (resultat, url) => !estHostile(resultat) // écarté avant que le modèle ne lise
|
|
164
|
+
});
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Des résultats https avec un titre, 8 au plus. Sans clé, rien n'est demandé
|
|
168
|
+
(`code: 'WEB_SEARCH_NO_KEY'`) ; une panne porte `'WEB_SEARCH_FAILED'`, jamais la clé.
|
|
169
|
+
|
|
46
170
|
## Registre d'outils
|
|
47
171
|
|
|
48
172
|
```js
|
|
@@ -103,6 +227,142 @@ Fonctionnalité non triviale dont une boucle d'agent de production a besoin,
|
|
|
103
227
|
mais dont le portage fidèle reste jugé trop ambitieux pour ce package. À
|
|
104
228
|
construire dans votre propre boucle, ou à couvrir dans un futur spec.
|
|
105
229
|
|
|
230
|
+
## Un disjoncteur par fournisseur, jamais un pour tous
|
|
231
|
+
|
|
232
|
+
Un seul disjoncteur partagé par toutes les dépendances extérieures a l'air
|
|
233
|
+
propre et c'est un piège : un reclasseur lent l'ouvrait, et le détecteur de
|
|
234
|
+
noms derrière le masquage s'éteignait avec lui pendant une minute. Ce qui
|
|
235
|
+
tombe doit être seul à s'arrêter.
|
|
236
|
+
|
|
237
|
+
Le paquet n'a pas de disjoncteur à lui : celui de `@astratra/resilience` (une
|
|
238
|
+
seule sonde en demi-ouverture) s'injecte.
|
|
239
|
+
|
|
240
|
+
```js
|
|
241
|
+
const { createCircuitBreaker } = require('@astratra/resilience');
|
|
242
|
+
const { createProviderRouter, isProviderOutage } = require('@astratra/ai');
|
|
243
|
+
|
|
244
|
+
const router = createProviderRouter({
|
|
245
|
+
providers,
|
|
246
|
+
breakers: (id) => createCircuitBreaker({ name: id, failureThreshold: 3, recoveryMs: 60_000, isFailure: isProviderOutage })
|
|
247
|
+
});
|
|
248
|
+
router.getStats()['groq:llama'].circuit; // 'closed' | 'open' | 'half-open'
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
`isProviderOutage` : délais, erreurs réseau, 408 et 5xx sont des pannes ; un
|
|
252
|
+
429 ne l'est pas (le refroidissement du routeur s'en charge), ni un 400/401/404
|
|
253
|
+
(c'est la requête ou la clé, pas le fournisseur). Un appel refusé par le
|
|
254
|
+
disjoncteur ne consomme aucun quota et ne compte pas comme échec du modèle.
|
|
255
|
+
`createBreakerPool` sert pour tout le reste (routes d'un service local de
|
|
256
|
+
modèles…) et **refuse une fabrique qui rendrait le même disjoncteur pour deux
|
|
257
|
+
clés** — c'est exactement le disjoncteur partagé.
|
|
258
|
+
|
|
259
|
+
## Masquer ce qui sort, démasquer ce qui revient
|
|
260
|
+
|
|
261
|
+
La question était masquée ; la recherche web ne l'était pas. Le modèle écrivait
|
|
262
|
+
la requête à partir de la question masquée, la boucle démasquait les paramètres
|
|
263
|
+
pour les outils qui ont besoin des vrais noms — et le nom de l'enfant partait
|
|
264
|
+
en clair chez le moteur de recherche. La règle porte donc sur la **direction** :
|
|
265
|
+
ce qui quitte la machine est masqué au moment où il la quitte.
|
|
266
|
+
|
|
267
|
+
```js
|
|
268
|
+
const { createReversibleMasker } = require('@astratra/ai');
|
|
269
|
+
|
|
270
|
+
const masker = createReversibleMasker({
|
|
271
|
+
names: registreDeLEcole, // sensible à la casse
|
|
272
|
+
patterns: [{ type: 'EMAIL', pattern: /[\w.+-]+@[\w-]+\.[\w.]+/g }],
|
|
273
|
+
detect: (texte) => serviceLocal.entites(texte), // NER local, jamais distant
|
|
274
|
+
});
|
|
275
|
+
|
|
276
|
+
// Routeur : un fournisseur externe reçoit le texte masqué, la réponse revient démasquée
|
|
277
|
+
// (y compris en flux). Un fournisseur `external: false` (sur la machine) reçoit le clair.
|
|
278
|
+
await router.ask(question, { complexity: 'simple' }, { masker });
|
|
279
|
+
|
|
280
|
+
// Boucle d'agent : un outil `external: true` reçoit des paramètres MASQUÉS.
|
|
281
|
+
registry.register({ name: 'web_search', external: true, /* … */ });
|
|
282
|
+
await runAgentLoop({ prompt, registry, router, userRole, masker });
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Un masqueur par conversation ; il **apprend** : un nom trouvé une fois est
|
|
286
|
+
masqué partout ensuite, avec le même jeton. Le registre est comparé en
|
|
287
|
+
respectant la casse et sur des mots entiers (« Grace » masqué, « grâce à »
|
|
288
|
+
intact), un nom de moins de trois lettres n'est jamais masqué, un nom absent du
|
|
289
|
+
texte ne crée aucun jeton, les détections sous 0,6 sont ignorées et le
|
|
290
|
+
détecteur ne reçoit que 1 500 caractères coupés sur un blanc. Au démasquage, un
|
|
291
|
+
modèle qui a perdu le `#` du jeton récupère quand même le nom, et
|
|
292
|
+
`#PERSON_0001` ne mange jamais le début de `#PERSON_00012`.
|
|
293
|
+
|
|
294
|
+
## Des passages dans une autre langue
|
|
295
|
+
|
|
296
|
+
Une question en anglais peut trouver sa meilleure réponse dans un texte qui
|
|
297
|
+
n'existe qu'en français. Chaque passage dit sa langue (`[fr]`) et une consigne
|
|
298
|
+
— la tienne, par langue — demande de traduire ce qui sert **en gardant la
|
|
299
|
+
référence d'origine**.
|
|
300
|
+
|
|
301
|
+
```js
|
|
302
|
+
const lignes = buildPassagesContext({
|
|
303
|
+
passages, // null = la recherche a échoué : on ne dit rien de la bibliothèque
|
|
304
|
+
lang: 'en',
|
|
305
|
+
texts: { header, footer, empty, foreign: 'A passage marked {languages} … keep its original reference.' }
|
|
306
|
+
});
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
`fr-FR` et `fr` sont la même langue (sous-étiquette principale). Un passage
|
|
310
|
+
étranger sans consigne est refusé plutôt que laissé à deviner au modèle.
|
|
311
|
+
|
|
312
|
+
## Les sources : lues, utilisées, contredites
|
|
313
|
+
|
|
314
|
+
- `createSourceLedger()` collecte les sources rendues par les outils ; un outil
|
|
315
|
+
qui en rend plusieurs ne rattache pas toute sa sortie à chacune.
|
|
316
|
+
- `usedSources(réponse, sources, preuves, options)` ne garde que celles sur
|
|
317
|
+
lesquelles la réponse s'appuie (son lien, une référence nommée des deux
|
|
318
|
+
côtés, assez de mots distinctifs communs). Rien n'est jamais ajouté.
|
|
319
|
+
- `findContradiction(réponse, extraits, { compare })` confronte chaque phrase
|
|
320
|
+
factuelle à l'extrait le plus proche via un modèle d'inférence local ; seule
|
|
321
|
+
une contradiction franche compte, un doute, une panne ou un délai dépassé ne
|
|
322
|
+
disent rien (`null`).
|
|
323
|
+
- `rerankResults(question, trouvés, { score })` range les résultats par
|
|
324
|
+
pertinence et les sources suivent ; sans score, l'ordre du moteur reste.
|
|
325
|
+
|
|
326
|
+
## Le texte de la réponse
|
|
327
|
+
|
|
328
|
+
`tidyMarkdown` ramène la réponse au Markdown qu'un téléphone dessine (avec
|
|
329
|
+
`remove`, des expressions que l'app ne montre jamais), `plainText` l'enlève
|
|
330
|
+
pour une voix, `wholeSentences` ramène un texte coupé à sa dernière phrase
|
|
331
|
+
entière, et `verifyQuotations(texte, { findReferences, resolve })` remplace une
|
|
332
|
+
citation infidèle suivie de sa référence par le vrai texte — ce qu'est une
|
|
333
|
+
référence et où vit son texte t'appartient.
|
|
334
|
+
|
|
335
|
+
## La langue de la réponse, la cadence, les points compatibles OpenAI
|
|
336
|
+
|
|
337
|
+
- `createLanguageDetector({ words, identify })` : les petits mots d'abord (un
|
|
338
|
+
« merci » ne se devine pas autrement), puis un identifiant injecté, cru
|
|
339
|
+
seulement au-dessus d'un seuil — bien plus haut pour deux mots.
|
|
340
|
+
- `createAskLimit({ max, windowMs, code })` : fenêtre glissante par personne ;
|
|
341
|
+
le refus porte un code et l'attente, jamais une phrase ; les comptes qui
|
|
342
|
+
n'écrivent plus sont oubliés (toutes les 500 demandes, et dès qu'une fenêtre
|
|
343
|
+
est passée depuis le dernier nettoyage).
|
|
344
|
+
- `createOpenAICompatibleProvider({ id, url, getKey, models, fetch })` : un
|
|
345
|
+
fournisseur pour le routeur. La clé est relue à chaque appel, une erreur porte
|
|
346
|
+
le statut HTTP (429 → refroidissement) et jamais la clé, des arguments d'outil
|
|
347
|
+
mal formés sont signalés (`invalid: true`) au lieu de faire tomber le tour, les
|
|
348
|
+
balises de réflexion ne sont jamais montrées.
|
|
349
|
+
|
|
350
|
+
## La boucle d'agent : outils en panne, budget de temps, dernier tour
|
|
351
|
+
|
|
352
|
+
```js
|
|
353
|
+
await runAgentLoop({
|
|
354
|
+
prompt, registry, router, userRole,
|
|
355
|
+
reportToolErrors: true, // un outil qui lève devient { error: 'tool_failed' } pour le modèle
|
|
356
|
+
toolTimeoutMs: 20_000, // … ou { error: 'tool_timeout' }
|
|
357
|
+
maxMs: 60_000, // budget total
|
|
358
|
+
finalInstruction: 'Réponds maintenant avec ce que tu as lu, sans outil.'
|
|
359
|
+
});
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Le modèle lit un code, jamais le message d'erreur. À court de tours ou de
|
|
363
|
+
temps, un dernier tour sans outils répond avec ce qui a été lu, plutôt qu'une
|
|
364
|
+
erreur.
|
|
365
|
+
|
|
106
366
|
## Tests
|
|
107
367
|
|
|
108
368
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/ai",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=20"
|
|
@@ -40,6 +40,7 @@
|
|
|
40
40
|
}
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
|
+
"@astratra/resilience": "^0.2.0",
|
|
43
44
|
"jest": "30.4.2",
|
|
44
45
|
"redis": "^4.7.0"
|
|
45
46
|
}
|
package/src/agentLoop.js
CHANGED
|
@@ -11,25 +11,49 @@ async function runAgentLoop({
|
|
|
11
11
|
userRole,
|
|
12
12
|
maxSteps = DEFAULT_MAX_STEPS,
|
|
13
13
|
onChunk,
|
|
14
|
-
confirmTool
|
|
14
|
+
confirmTool,
|
|
15
|
+
masker,
|
|
16
|
+
reportToolErrors = false,
|
|
17
|
+
toolTimeoutMs,
|
|
18
|
+
maxMs,
|
|
19
|
+
finalInstruction,
|
|
20
|
+
now = Date.now
|
|
15
21
|
}) {
|
|
16
22
|
if (!registry) throw new AppError('agentLoop requires a registry', 500);
|
|
17
23
|
if (!router || typeof router.ask !== 'function') throw new AppError('agentLoop requires a router', 500);
|
|
24
|
+
if (masker && (typeof masker.mask !== 'function' || typeof masker.unmask !== 'function')) {
|
|
25
|
+
throw new AppError('agentLoop requires masker from createReversibleMasker()', 500);
|
|
26
|
+
}
|
|
18
27
|
|
|
19
28
|
const messages = Array.isArray(history) ? [...history] : [];
|
|
20
29
|
messages.push({ role: 'user', content: prompt });
|
|
30
|
+
const started = now();
|
|
31
|
+
|
|
32
|
+
/* The question is read by the entity detector once, so every name in it is
|
|
33
|
+
known before the first byte leaves; afterwards the prompt is masked with
|
|
34
|
+
what the masker has learnt. Inside the loop everything stays in clear —
|
|
35
|
+
masking happens at the door, on the way out. */
|
|
36
|
+
if (masker && typeof masker.maskAsync === 'function') await masker.maskAsync(String(prompt || ''));
|
|
21
37
|
|
|
22
|
-
|
|
23
|
-
const
|
|
38
|
+
async function askModel(modelPrompt) {
|
|
39
|
+
const outbound = masker ? masker.mask(modelPrompt) : modelPrompt;
|
|
40
|
+
const raw = await router.ask(outbound, {
|
|
41
|
+
complexity: 'agent',
|
|
42
|
+
intent: 'agent_loop',
|
|
43
|
+
estimatedTokens: estimateTokens(outbound)
|
|
44
|
+
}, ctx);
|
|
45
|
+
const readable = masker ? unmaskAnswer(masker, raw) : raw;
|
|
24
46
|
// onChunk, when provided, is called with each chunk AS IT ARRIVES if
|
|
25
47
|
// router.ask() returns a stream — real token-by-token streaming to the
|
|
26
48
|
// caller. The loop itself still needs the fully-assembled text to
|
|
27
49
|
// detect a <tool_call>, so it accumulates in parallel regardless.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
50
|
+
return stringifyModelResponse(readable, onChunk);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const outOfTime = () => Number.isFinite(maxMs) && now() - started >= maxMs;
|
|
54
|
+
|
|
55
|
+
for (let step = 0; step < maxSteps && !outOfTime(); step += 1) {
|
|
56
|
+
const response = await askModel(buildPrompt(registry, userRole, messages));
|
|
33
57
|
const toolCall = parseToolCall(response);
|
|
34
58
|
|
|
35
59
|
if (!toolCall) {
|
|
@@ -61,19 +85,70 @@ async function runAgentLoop({
|
|
|
61
85
|
}
|
|
62
86
|
}
|
|
63
87
|
|
|
64
|
-
|
|
88
|
+
/* A tool that reaches OUTSIDE (a web search, a third-party API) gets its
|
|
89
|
+
parameters masked: the model wrote them from a masked prompt, the loop
|
|
90
|
+
read them in clear, and they must not leave in clear. */
|
|
91
|
+
const params = masker && tool.external === true ? masker.maskDeep(toolCall.params) : toolCall.params;
|
|
92
|
+
let result;
|
|
93
|
+
try {
|
|
94
|
+
result = await runTool(tool, params, ctx, toolTimeoutMs);
|
|
95
|
+
} catch (error) {
|
|
96
|
+
if (!reportToolErrors) throw error;
|
|
97
|
+
/* The model reads a code, never the error message: it may quote
|
|
98
|
+
internals, and it is not the model's business. */
|
|
99
|
+
result = { error: error && error.code === 'TOOL_TIMEOUT' ? 'tool_timeout' : 'tool_failed' };
|
|
100
|
+
}
|
|
101
|
+
if (masker && tool.external === true) result = masker.unmaskDeep(result);
|
|
102
|
+
const serialized = JSON.stringify(result);
|
|
103
|
+
/* Your own data (a class list, a file) carries names the register may not
|
|
104
|
+
know: the detector reads the result before it can reach the prompt. */
|
|
105
|
+
if (masker && tool.external !== true && typeof masker.maskAsync === 'function') await masker.maskAsync(String(serialized));
|
|
65
106
|
messages.push({ role: 'assistant', content: response });
|
|
66
107
|
messages.push({
|
|
67
108
|
role: 'tool',
|
|
68
|
-
content: `<tool_result name="${tool.name}">${
|
|
109
|
+
content: `<tool_result name="${tool.name}">${serialized}</tool_result>`
|
|
69
110
|
});
|
|
70
111
|
}
|
|
71
112
|
|
|
113
|
+
/* Out of steps or time: one last turn without tools, when the caller says
|
|
114
|
+
how to ask for it — an answer with what was read beats an error. */
|
|
115
|
+
if (typeof finalInstruction === 'string' && finalInstruction.trim()) {
|
|
116
|
+
const last = await askModel(`${buildPrompt(null, userRole, messages)}\n\n${finalInstruction}`);
|
|
117
|
+
const stray = parseToolCallSafely(last);
|
|
118
|
+
return stray ? last.replace(TOOL_CALL_PATTERN, '').trim() : last;
|
|
119
|
+
}
|
|
120
|
+
|
|
72
121
|
throw new AppError(`agentLoop reached maxSteps (${maxSteps}) before a final answer`, 500);
|
|
73
122
|
}
|
|
74
123
|
|
|
124
|
+
async function runTool(tool, params, ctx, timeoutMs) {
|
|
125
|
+
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return tool.handler(params, ctx);
|
|
126
|
+
let timer;
|
|
127
|
+
const timeout = new Promise((_resolve, reject) => {
|
|
128
|
+
timer = setTimeout(() => reject(Object.assign(new Error(`Tool "${tool.name}" timed out`), { code: 'TOOL_TIMEOUT' })), timeoutMs);
|
|
129
|
+
});
|
|
130
|
+
try {
|
|
131
|
+
return await Promise.race([Promise.resolve().then(() => tool.handler(params, ctx)), timeout]);
|
|
132
|
+
} finally {
|
|
133
|
+
clearTimeout(timer);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function unmaskAnswer(masker, raw) {
|
|
138
|
+
if (isAsyncIterable(raw) && typeof masker.unmaskStream === 'function') return masker.unmaskStream(raw);
|
|
139
|
+
return typeof raw === 'string' ? masker.unmask(raw) : raw;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function parseToolCallSafely(text) {
|
|
143
|
+
try {
|
|
144
|
+
return parseToolCall(text);
|
|
145
|
+
} catch (_error) {
|
|
146
|
+
return { name: 'invalid', params: {} };
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
75
150
|
function buildPrompt(registry, userRole, messages) {
|
|
76
|
-
const tools = registry.formatToolsForPrompt(userRole);
|
|
151
|
+
const tools = registry ? registry.formatToolsForPrompt(userRole) : '';
|
|
77
152
|
const renderedHistory = messages.map(message => {
|
|
78
153
|
if (typeof message === 'string') return message;
|
|
79
154
|
return `${message.role || 'message'}: ${message.content || ''}`;
|
|
@@ -85,6 +160,8 @@ function buildPrompt(registry, userRole, messages) {
|
|
|
85
160
|
].filter(Boolean).join('\n\n');
|
|
86
161
|
}
|
|
87
162
|
|
|
163
|
+
const TOOL_CALL_PATTERN = /<tool_call\s+name="([^"]+)">\s*([\s\S]*?)\s*<\/tool_call>/gi;
|
|
164
|
+
|
|
88
165
|
function parseToolCall(text) {
|
|
89
166
|
const match = String(text || '').match(/<tool_call\s+name="([^"]+)">\s*([\s\S]*?)\s*<\/tool_call>/i);
|
|
90
167
|
if (!match) return null;
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The last look at an answer before a screen draws it, or a voice reads it.
|
|
3
|
+
*
|
|
4
|
+
* A mobile Markdown renderer draws a small subset — **bold**, "- " and "1. "
|
|
5
|
+
* lists, "### " headings, "> " quotes — and shows everything else as raw
|
|
6
|
+
* symbols. tidyMarkdown brings the answer back to that subset; plainText
|
|
7
|
+
* strips it for a voice or a notification.
|
|
8
|
+
*
|
|
9
|
+
* verifyQuotations checks every quotation that cites a reference against the
|
|
10
|
+
* text you hold. A model quotes from memory, or from another edition, despite
|
|
11
|
+
* its instructions; an unfaithful quotation is replaced by the true text. What
|
|
12
|
+
* a "reference" is and where its text lives is yours (verses, articles of law,
|
|
13
|
+
* clauses of a contract): both are injected.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/** Markdown and stray asterisks out, the words kept: what is read aloud. */
|
|
17
|
+
function plainText(text) {
|
|
18
|
+
return String(text === null || text === undefined ? '' : text)
|
|
19
|
+
.replace(/^#{1,6}\s+/gm, '')
|
|
20
|
+
.replace(/^>\s?/gm, '')
|
|
21
|
+
.replace(/^\s*[-*•]\s+/gm, '')
|
|
22
|
+
.replace(/\*\*([^*]+)\*\*/g, '$1')
|
|
23
|
+
.replace(/__([^_]+)__/g, '$1')
|
|
24
|
+
.replace(/\*([^*\s][^*]*)\*/g, '$1')
|
|
25
|
+
.replace(/`([^`]+)`/g, '$1')
|
|
26
|
+
.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
|
|
27
|
+
.replace(/ ?\*+ ?/g, ' ')
|
|
28
|
+
.replace(/\n{3,}/g, '\n\n')
|
|
29
|
+
.trim();
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @param {string} text
|
|
34
|
+
* @param {object} [options]
|
|
35
|
+
* @param {boolean} [options.removeEmoji] drop emoji — for an app that draws its own symbols. Default false.
|
|
36
|
+
* @param {RegExp[]} [options.remove] ce que l'app ne montre jamais, retiré après les marques
|
|
37
|
+
* (des lettres d'un autre alphabet recopiées d'un titre, par exemple). Chaque expression est globale.
|
|
38
|
+
*/
|
|
39
|
+
function tidyMarkdown(text, options = {}) {
|
|
40
|
+
let out = String(text === null || text === undefined ? '' : text)
|
|
41
|
+
.replace(/```\w*\n?/g, '')
|
|
42
|
+
/* A rule drawn across ("---", "***") is only a pause: a blank line. */
|
|
43
|
+
.replace(/^[ \t]*([-*_])(?:[ \t]*\1){2,}[ \t]*$/gm, '')
|
|
44
|
+
/* Tables: the separator row goes, each row becomes "a · b · c". */
|
|
45
|
+
.replace(/^[ \t]*\|[ \t:|-]+\|[ \t]*(\n|$)/gm, '')
|
|
46
|
+
.replace(/^[ \t]*\|(.*)\|[ \t]*$/gm, (_row, cells) => cells.split('|').map((cell) => cell.trim()).filter(Boolean).join(' · '))
|
|
47
|
+
.replace(/^#{1,6}\s+(.+)$/gm, '### $1')
|
|
48
|
+
.replace(/^(\s*)[*•]\s+/gm, '$1- ')
|
|
49
|
+
.replace(/__([^_\n]+)__/g, '**$1**')
|
|
50
|
+
.replace(/(^|[^*])\*(?!\*)([^*\n]+?)\*(?!\*)/g, '$1$2')
|
|
51
|
+
.replace(/(^|[^*])\*(?!\*)/g, '$1')
|
|
52
|
+
.replace(/`([^`]+)`/g, '$1')
|
|
53
|
+
.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1');
|
|
54
|
+
for (const pattern of options.remove || []) {
|
|
55
|
+
if (!(pattern instanceof RegExp) || !pattern.global) throw new Error('tidyMarkdown: every options.remove entry must be a global RegExp.');
|
|
56
|
+
out = out.replace(pattern, '');
|
|
57
|
+
}
|
|
58
|
+
if (options.removeEmoji) {
|
|
59
|
+
out = out.replace(/[\p{Extended_Pictographic}\p{Emoji_Modifier}\u{FE0F}\u{200D}]/gu, '');
|
|
60
|
+
}
|
|
61
|
+
return out
|
|
62
|
+
.replace(/(\S)[ \t]{2,}/g, '$1 ')
|
|
63
|
+
.replace(/[ \t]+$/gm, '')
|
|
64
|
+
.replace(/\n{3,}/g, '\n\n')
|
|
65
|
+
.trim();
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Un texte coupé à sa longueur, ramené à sa dernière phrase entière : jamais
|
|
70
|
+
* un mot coupé en deux. Sans fin de phrase, le texte reste tel quel.
|
|
71
|
+
* @param {string} text
|
|
72
|
+
* @param {object} [options]
|
|
73
|
+
* @param {string[]} [options.marks] ce qui termine une phrase. Défaut : . ! ? … » ) "
|
|
74
|
+
*/
|
|
75
|
+
function wholeSentences(text, options = {}) {
|
|
76
|
+
const trimmed = String(text === null || text === undefined ? '' : text).trimEnd();
|
|
77
|
+
const marks = options.marks || ['.', '!', '?', '…', '»', ')', '"'];
|
|
78
|
+
const end = Math.max(...marks.map((mark) => trimmed.lastIndexOf(mark)));
|
|
79
|
+
return end > 0 ? trimmed.slice(0, end + 1) : trimmed;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/* A quotation between guillemets, curly quotes or straight quotes. */
|
|
83
|
+
const QUOTATION = /(«\s*)([^«»]+?)(\s*»)|(“)([^“”]+)(”)|(")([^"\n]+)(")/g;
|
|
84
|
+
/* What may stand between a quotation and the reference saying where it comes from. */
|
|
85
|
+
const BETWEEN = /^\s*\(?\s*$/;
|
|
86
|
+
const ELLIPSIS = /…|\.\.\./;
|
|
87
|
+
|
|
88
|
+
/* Words only: no punctuation, no accents, no case. */
|
|
89
|
+
const foldWords = (text) => ` ${String(text).normalize('NFD').replace(/\p{M}/gu, '').toLowerCase().replace(/[^\p{L}\d]+/gu, ' ').trim()} `;
|
|
90
|
+
|
|
91
|
+
/** Faithful when each piece of the quotation (cut by an ellipsis) is in the source. */
|
|
92
|
+
function isFaithfulQuotation(quoted, source) {
|
|
93
|
+
const haystack = foldWords(source);
|
|
94
|
+
return String(quoted).split(ELLIPSIS).map(foldWords).filter((piece) => piece.trim()).every((piece) => haystack.includes(piece));
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* @param {string} text
|
|
99
|
+
* @param {object} options
|
|
100
|
+
* @param {Function} options.findReferences (text) => [{ start, end, refs }] — places cited, with offsets.
|
|
101
|
+
* @param {Function} options.resolve async (refs) => the true text of those places, or null.
|
|
102
|
+
* @returns {Promise<string>} the text, each unfaithful quotation followed by a
|
|
103
|
+
* reference replaced by the true text. When references cannot be read, unchanged.
|
|
104
|
+
*/
|
|
105
|
+
async function verifyQuotations(text, options = {}) {
|
|
106
|
+
const source = String(text === null || text === undefined ? '' : text);
|
|
107
|
+
if (typeof options.findReferences !== 'function' || typeof options.resolve !== 'function') {
|
|
108
|
+
throw new Error('verifyQuotations requires options.findReferences and options.resolve.');
|
|
109
|
+
}
|
|
110
|
+
let references;
|
|
111
|
+
try {
|
|
112
|
+
references = (await options.findReferences(source)) || [];
|
|
113
|
+
} catch (_error) {
|
|
114
|
+
return source;
|
|
115
|
+
}
|
|
116
|
+
const replacements = [];
|
|
117
|
+
for (const match of source.matchAll(QUOTATION)) {
|
|
118
|
+
const groups = match.slice(1);
|
|
119
|
+
const triple = [groups.slice(0, 3), groups.slice(3, 6), groups.slice(6, 9)].find((group) => group[1] !== undefined);
|
|
120
|
+
const end = match.index + match[0].length;
|
|
121
|
+
const reference = references.find((found) => found.start >= end && BETWEEN.test(source.slice(end, found.start)));
|
|
122
|
+
if (!reference) continue;
|
|
123
|
+
let truth = null;
|
|
124
|
+
try {
|
|
125
|
+
truth = await options.resolve(reference.refs);
|
|
126
|
+
} catch (_error) {
|
|
127
|
+
truth = null;
|
|
128
|
+
}
|
|
129
|
+
if (!truth || isFaithfulQuotation(triple[1], truth)) continue;
|
|
130
|
+
replacements.push({ start: match.index, end, value: `${triple[0]}${truth}${triple[2]}` });
|
|
131
|
+
}
|
|
132
|
+
let out = source;
|
|
133
|
+
for (const { start, end, value } of replacements.reverse()) out = out.slice(0, start) + value + out.slice(end);
|
|
134
|
+
return out;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
module.exports = { plainText, tidyMarkdown, verifyQuotations, isFaithfulQuotation, wholeSentences };
|
package/src/askLimit.js
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How often one account may ask the AI: a sliding window per person, in
|
|
3
|
+
* memory — one process. For several instances, put the counter in Redis (the
|
|
4
|
+
* provider router already does for provider quotas).
|
|
5
|
+
*
|
|
6
|
+
* Each area (chat, image, voice) keeps its own limiter with its own code. The
|
|
7
|
+
* refusal carries a code and the wait, never a sentence: the client translates.
|
|
8
|
+
*
|
|
9
|
+
* Accounts that stop asking are forgotten: a map that only grows is a slow
|
|
10
|
+
* memory leak on a server that runs for months.
|
|
11
|
+
*/
|
|
12
|
+
const { AppError } = require('@astratra/core');
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* @param {object} options
|
|
16
|
+
* @param {number} options.max asks allowed in the window.
|
|
17
|
+
* @param {number} options.windowMs
|
|
18
|
+
* @param {string} [options.code] Default 'AI_RATE_LIMITED'.
|
|
19
|
+
* @param {number} [options.sweepEvery] asks between two clean-ups. Default 500.
|
|
20
|
+
* Une fenêtre passée depuis le dernier nettoyage en déclenche un aussi : un
|
|
21
|
+
* serveur peu sollicité oublie ses comptes inactifs sans attendre 500 demandes.
|
|
22
|
+
*/
|
|
23
|
+
function createAskLimit(options = {}) {
|
|
24
|
+
const { max, windowMs } = options;
|
|
25
|
+
if (!Number.isInteger(max) || max < 1) throw new Error('createAskLimit requires an integer options.max >= 1.');
|
|
26
|
+
if (!Number.isFinite(windowMs) || windowMs <= 0) throw new Error('createAskLimit requires options.windowMs > 0.');
|
|
27
|
+
const code = options.code || 'AI_RATE_LIMITED';
|
|
28
|
+
const sweepEvery = options.sweepEvery || 500;
|
|
29
|
+
const asks = new Map();
|
|
30
|
+
let sinceSweep = 0;
|
|
31
|
+
let sweptAt = -Infinity;
|
|
32
|
+
|
|
33
|
+
function sweep(now) {
|
|
34
|
+
for (const [id, times] of asks) {
|
|
35
|
+
const recent = times.filter((at) => now - at < windowMs);
|
|
36
|
+
if (recent.length) asks.set(id, recent);
|
|
37
|
+
else asks.delete(id);
|
|
38
|
+
}
|
|
39
|
+
sweptAt = now;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** What `take` would answer, without counting an ask. */
|
|
43
|
+
function peek(subject, now = Date.now()) {
|
|
44
|
+
const recent = (asks.get(String(subject)) || []).filter((at) => now - at < windowMs);
|
|
45
|
+
if (recent.length < max) return { allowed: true, remaining: max - recent.length, retryInMs: 0 };
|
|
46
|
+
return { allowed: false, remaining: 0, retryInMs: Math.max(0, recent[0] + windowMs - now) };
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Count one ask; throws a 429 AppError carrying `code` and `retryInMs` past the limit. */
|
|
50
|
+
function take(subject, now = Date.now()) {
|
|
51
|
+
const id = String(subject);
|
|
52
|
+
sinceSweep += 1;
|
|
53
|
+
if (sinceSweep >= sweepEvery || now - sweptAt >= windowMs) {
|
|
54
|
+
sinceSweep = 0;
|
|
55
|
+
sweep(now);
|
|
56
|
+
}
|
|
57
|
+
const verdict = peek(id, now);
|
|
58
|
+
if (!verdict.allowed) {
|
|
59
|
+
const error = new AppError(code, 429);
|
|
60
|
+
error.code = code;
|
|
61
|
+
error.retryInMs = verdict.retryInMs;
|
|
62
|
+
throw error;
|
|
63
|
+
}
|
|
64
|
+
const recent = (asks.get(id) || []).filter((at) => now - at < windowMs);
|
|
65
|
+
recent.push(now);
|
|
66
|
+
asks.set(id, recent);
|
|
67
|
+
return { allowed: true, remaining: max - recent.length, retryInMs: 0 };
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
return { take, peek, reset: (subject) => (subject === undefined ? asks.clear() : asks.delete(String(subject))), size: () => asks.size, sweep };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
module.exports = { createAskLimit };
|