@astratra/ai 1.4.0 → 1.6.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 +243 -7
- package/deploy/llama-cpp/.env.example +10 -0
- package/deploy/llama-cpp/docker-compose.yml +47 -0
- package/package.json +7 -4
- package/src/agentLoop.js +101 -5
- package/src/answerText.js +21 -1
- package/src/askLimit.js +5 -1
- package/src/eventStream.js +47 -0
- package/src/gemini.js +152 -0
- package/src/index.d.ts +293 -13
- package/src/index.js +6 -1
- package/src/llamaCpp.js +192 -0
- package/src/modelAnswers.js +119 -0
- package/src/nativeTools.js +256 -0
- package/src/openaiCompatible.js +33 -45
- package/src/providerRouter.js +154 -40
- package/src/toolRegistry.js +13 -2
- 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
|
|
@@ -53,6 +177,7 @@ registry.register({
|
|
|
53
177
|
name: 'get_patient_record',
|
|
54
178
|
description: "Récupère le dossier d'un patient par son id",
|
|
55
179
|
type: 'read',
|
|
180
|
+
risk: 'LOW', // LOW, MEDIUM ou HIGH ; absent = UNKNOWN
|
|
56
181
|
roles: ['doctor', 'admin'],
|
|
57
182
|
params: { patientId: 'string' },
|
|
58
183
|
handler: async ({ patientId }, ctx) => patientStore.findById(patientId)
|
|
@@ -98,6 +223,43 @@ comme résultat d'outil) et continue, il peut réagir (expliquer, proposer
|
|
|
98
223
|
autre chose, s'arrêter). Omis, chaque outil autorisé s'exécute automatiquement,
|
|
99
224
|
comme avant.
|
|
100
225
|
|
|
226
|
+
### Garde-fous de la boucle, résultats volumineux et risque
|
|
227
|
+
|
|
228
|
+
Les appels répétés avec le même nom et les mêmes paramètres JSON (l'ordre des
|
|
229
|
+
clés d'objet ne compte pas) reçoivent un rappel aux répétitions 3 et 5, puis
|
|
230
|
+
la boucle s'arrête à 8. Ces seuils se règlent avec `loopGuard`; `onEvent`
|
|
231
|
+
reçoit `tool_loop_warning` ou `tool_loop_stopped`. Le nombre d'étapes par
|
|
232
|
+
défaut reste 5 : l'arrêt à 8 ne joue que si `maxSteps` est réglé à 8 ou plus.
|
|
233
|
+
|
|
234
|
+
```js
|
|
235
|
+
await runAgentLoop({
|
|
236
|
+
prompt, registry, router, userRole: 'doctor',
|
|
237
|
+
loopGuard: { reminder: 3, firmReminder: 5, stop: 8 },
|
|
238
|
+
spill: { threshold: 12_000 },
|
|
239
|
+
confirmationPolicy: { threshold: 'HIGH' },
|
|
240
|
+
riskAnalyzers: [async (call, ctx, tool) => classifier(call, ctx, tool)],
|
|
241
|
+
pendingActions
|
|
242
|
+
});
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Au-dessus du seuil (`spill.threshold`, 12 000 caractères par défaut), le
|
|
246
|
+
résultat complet est écrit dans `spill.store` (stockage mémoire par défaut).
|
|
247
|
+
Le modèle reçoit un extrait et un identifiant, puis peut appeler
|
|
248
|
+
`read_spilled_result` avec `{ id, start, length }` pour lire une tranche. Si
|
|
249
|
+
l'écriture échoue, le contenu est supprimé de la réponse et le modèle reçoit
|
|
250
|
+
`result_storage_failed`. Un stockage injecté expose `set(id, value)` et
|
|
251
|
+
`get(id)`.
|
|
252
|
+
|
|
253
|
+
Les risques possibles sont `LOW`, `MEDIUM`, `HIGH` et `UNKNOWN` (valeur des
|
|
254
|
+
outils sans déclaration). La politique de confirmation est inactive par
|
|
255
|
+
défaut, pour préserver l'exécution existante. Elle accepte `'always'`,
|
|
256
|
+
`'never'` ou `{ threshold: 'MEDIUM' }`; dans ce dernier cas, les risques au
|
|
257
|
+
moins aussi élevés que le seuil, dont `UNKNOWN`, demandent une confirmation.
|
|
258
|
+
Les `riskAnalyzers` reçoivent l'appel, le contexte et l'outil ; le niveau le
|
|
259
|
+
plus élevé entre l'outil et les analyseurs l'emporte. Les appels à confirmer
|
|
260
|
+
sont enregistrés par `pendingActions.propose()` et attendent l'approbation
|
|
261
|
+
via le cycle de vie déjà fourni par `createPendingActions`.
|
|
262
|
+
|
|
101
263
|
**Périmètre V0 — toujours volontairement exclu :** gestion d'images/vision.
|
|
102
264
|
Fonctionnalité non triviale dont une boucle d'agent de production a besoin,
|
|
103
265
|
mais dont le portage fidèle reste jugé trop ambitieux pour ce package. À
|
|
@@ -201,10 +363,12 @@ const lignes = buildPassagesContext({
|
|
|
201
363
|
|
|
202
364
|
## Le texte de la réponse
|
|
203
365
|
|
|
204
|
-
`tidyMarkdown` ramène la réponse au Markdown qu'un téléphone dessine
|
|
205
|
-
`
|
|
206
|
-
|
|
207
|
-
|
|
366
|
+
`tidyMarkdown` ramène la réponse au Markdown qu'un téléphone dessine (avec
|
|
367
|
+
`remove`, des expressions que l'app ne montre jamais), `plainText` l'enlève
|
|
368
|
+
pour une voix, `wholeSentences` ramène un texte coupé à sa dernière phrase
|
|
369
|
+
entière, et `verifyQuotations(texte, { findReferences, resolve })` remplace une
|
|
370
|
+
citation infidèle suivie de sa référence par le vrai texte — ce qu'est une
|
|
371
|
+
référence et où vit son texte t'appartient.
|
|
208
372
|
|
|
209
373
|
## La langue de la réponse, la cadence, les points compatibles OpenAI
|
|
210
374
|
|
|
@@ -213,7 +377,8 @@ texte — ce qu'est une référence et où vit son texte t'appartient.
|
|
|
213
377
|
seulement au-dessus d'un seuil — bien plus haut pour deux mots.
|
|
214
378
|
- `createAskLimit({ max, windowMs, code })` : fenêtre glissante par personne ;
|
|
215
379
|
le refus porte un code et l'attente, jamais une phrase ; les comptes qui
|
|
216
|
-
n'écrivent plus sont oubliés
|
|
380
|
+
n'écrivent plus sont oubliés (toutes les 500 demandes, et dès qu'une fenêtre
|
|
381
|
+
est passée depuis le dernier nettoyage).
|
|
217
382
|
- `createOpenAICompatibleProvider({ id, url, getKey, models, fetch })` : un
|
|
218
383
|
fournisseur pour le routeur. La clé est relue à chaque appel, une erreur porte
|
|
219
384
|
le statut HTTP (429 → refroidissement) et jamais la clé, des arguments d'outil
|
|
@@ -236,6 +401,77 @@ Le modèle lit un code, jamais le message d'erreur. À court de tours ou de
|
|
|
236
401
|
temps, un dernier tour sans outils répond avec ce qui a été lu, plutôt qu'une
|
|
237
402
|
erreur.
|
|
238
403
|
|
|
404
|
+
## llama.cpp : un modèle sur CPU, sur ton VPS
|
|
405
|
+
|
|
406
|
+
Fournisseur « **llama.cpp server** » : un modèle qui tourne sur **CPU** (un VPS
|
|
407
|
+
sans GPU) derrière l'API compatible OpenAI de `llama-server`. Aucune dépendance
|
|
408
|
+
(`src/llamaCpp.js`). C'est un client ; il ne lance rien. Le serveur se lance avec
|
|
409
|
+
le `docker-compose` de `deploy/llama-cpp/`. Ce n'est pas un doublon de
|
|
410
|
+
`createOpenAICompatibleProvider` : celui-ci branche un modèle dans le routeur et
|
|
411
|
+
rend `{ status }` pour une erreur HTTP, alors qu'un serveur hébergé par toi a
|
|
412
|
+
besoin de sa santé, du chargement du modèle (503) et d'erreurs typées.
|
|
413
|
+
|
|
414
|
+
### Client
|
|
415
|
+
|
|
416
|
+
```js
|
|
417
|
+
const { createLlamaCppProvider } = require('@astratra/ai');
|
|
418
|
+
|
|
419
|
+
const llm = createLlamaCppProvider({
|
|
420
|
+
baseUrl: 'http://127.0.0.1:8080', // avec ou sans /v1
|
|
421
|
+
apiKey: process.env.LLAMA_API_KEY,
|
|
422
|
+
model: 'local', // l'alias donné au serveur (facultatif)
|
|
423
|
+
timeoutMs: 120_000,
|
|
424
|
+
});
|
|
425
|
+
|
|
426
|
+
await llm.waitUntilReady({ timeoutMs: 120_000 }); // le chargement du modèle prend du temps
|
|
427
|
+
console.log(await llm.health()); // { ok, status: 'ok'|'loading'|'unauthorized'|'error'|'unreachable'|'timeout', latencyMs }
|
|
428
|
+
console.log(await llm.listModels()); // [{ id: 'local', ownedBy: 'llamacpp' }]
|
|
429
|
+
|
|
430
|
+
const { text, usage } = await llm.chat([{ role: 'user', content: 'Bonjour' }], { temperature: 0.2 });
|
|
431
|
+
for await (const piece of llm.chatStream([{ role: 'user', content: 'Raconte-moi une histoire' }])) process.stdout.write(piece);
|
|
432
|
+
|
|
433
|
+
llm.toOpenAICompatible(); // { baseURL: '…/v1', apiKey, model } pour tout autre client compatible OpenAI
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
`health()` ne lance jamais d'exception (c'est une sonde). Les autres appels
|
|
437
|
+
lancent `LocalLlmError` avec `code` : `UNREACHABLE`, `TIMEOUT`, `UNAUTHORIZED`,
|
|
438
|
+
`LOADING` (503, modèle pas chargé), `HTTP_ERROR` (avec `status`), `INVALID_RESPONSE`.
|
|
439
|
+
|
|
440
|
+
### Lancer `llama-server` sur un VPS CPU
|
|
441
|
+
|
|
442
|
+
Image officielle : `ghcr.io/ggml-org/llama.cpp:server` (CPU ; épingle un tag
|
|
443
|
+
`server-b<numéro>` en production).
|
|
444
|
+
|
|
445
|
+
```bash
|
|
446
|
+
cd packages/ai/deploy/llama-cpp
|
|
447
|
+
cp .env.example .env # remplis LLAMA_API_KEY (longue valeur aléatoire) et LLAMA_MODEL_FILE
|
|
448
|
+
mkdir -p models # y déposer le fichier .gguf (quantisation Q4_K_M : bon compromis)
|
|
449
|
+
docker compose up -d
|
|
450
|
+
docker compose logs -f llama # attendre « server is listening »
|
|
451
|
+
curl -H "Authorization: Bearer $LLAMA_API_KEY" http://127.0.0.1:8080/v1/models
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
Points à régler :
|
|
455
|
+
|
|
456
|
+
- **`LLAMA_THREADS`** : cœurs *physiques*, pas vCPU. Trop de fils ralentit.
|
|
457
|
+
- **`LLAMA_PARALLEL`** : requêtes simultanées. Le contexte (`LLAMA_CTX`) est
|
|
458
|
+
**partagé** : chacune dispose de `LLAMA_CTX / LLAMA_PARALLEL` jetons.
|
|
459
|
+
- **Mémoire** : prévoir la taille du fichier .gguf + ~1 à 2 Go pour le contexte ;
|
|
460
|
+
`LLAMA_MEMORY_LIMIT` plafonne le conteneur.
|
|
461
|
+
- **Débit** : sur CPU, un modèle de 3 à 4 milliards de paramètres en Q4 donne de
|
|
462
|
+
l'ordre de quelques à une dizaine de jetons par seconde selon le VPS ; à
|
|
463
|
+
mesurer sur le tien avant de promettre quoi que ce soit.
|
|
464
|
+
- Le port n'est publié que sur `127.0.0.1` : l'ouverture au public passe par un
|
|
465
|
+
proxy avec TLS, et la clé API reste obligatoire.
|
|
466
|
+
- La clé est lue dans l'environnement (`LLAMA_API_KEY`), jamais en argument.
|
|
467
|
+
|
|
468
|
+
### Limites
|
|
469
|
+
|
|
470
|
+
Pas de répartition de charge ni de repli intégrés au client : pour router ce
|
|
471
|
+
serveur avec les autres fournisseurs, donne `toOpenAICompatible()` (adresse et clé)
|
|
472
|
+
à `createOpenAICompatibleProvider`. Testé avec un faux
|
|
473
|
+
serveur HTTP ; le vrai `llama-server` n'a pas été lancé dans ce dépôt.
|
|
474
|
+
|
|
239
475
|
## Tests
|
|
240
476
|
|
|
241
477
|
```bash
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Copie en .env (jamais commité) puis remplis.
|
|
2
|
+
LLAMA_API_KEY=remplace-par-une-longue-valeur-aleatoire
|
|
3
|
+
LLAMA_MODEL_FILE=nom-du-modele-Q4_K_M.gguf
|
|
4
|
+
LLAMA_ALIAS=local
|
|
5
|
+
LLAMA_CTX=8192
|
|
6
|
+
LLAMA_THREADS=4
|
|
7
|
+
LLAMA_PARALLEL=2
|
|
8
|
+
LLAMA_MEMORY_LIMIT=6g
|
|
9
|
+
LLAMA_MODELS_DIR=./models
|
|
10
|
+
LLAMA_PORT=8080
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# llama.cpp en inférence CPU sur un VPS — API compatible OpenAI sur le port 8080.
|
|
2
|
+
# NE démarre rien tout seul : `docker compose up -d` après avoir lu le README du paquet.
|
|
3
|
+
#
|
|
4
|
+
# Image officielle : ghcr.io/ggml-org/llama.cpp:server (CPU). Épingle un tag
|
|
5
|
+
# `server-b<numéro>` en production plutôt que le tag flottant.
|
|
6
|
+
services:
|
|
7
|
+
llama:
|
|
8
|
+
image: ${LLAMA_IMAGE:-ghcr.io/ggml-org/llama.cpp:server}
|
|
9
|
+
restart: unless-stopped
|
|
10
|
+
# Écoute en local seulement : la sortie publique passe par un proxy avec TLS (nginx, Caddy).
|
|
11
|
+
ports:
|
|
12
|
+
- "127.0.0.1:${LLAMA_PORT:-8080}:8080"
|
|
13
|
+
volumes:
|
|
14
|
+
# Les fichiers .gguf, à télécharger une fois (voir README).
|
|
15
|
+
- ${LLAMA_MODELS_DIR:-./models}:/models:ro
|
|
16
|
+
environment:
|
|
17
|
+
# La clé est lue dans l'environnement, jamais passée en argument (visible dans `ps`).
|
|
18
|
+
LLAMA_API_KEY: ${LLAMA_API_KEY:?définis LLAMA_API_KEY dans .env}
|
|
19
|
+
command:
|
|
20
|
+
- --host
|
|
21
|
+
- 0.0.0.0
|
|
22
|
+
- --port
|
|
23
|
+
- "8080"
|
|
24
|
+
- --model
|
|
25
|
+
- /models/${LLAMA_MODEL_FILE:?définis LLAMA_MODEL_FILE dans .env}
|
|
26
|
+
- --alias
|
|
27
|
+
- ${LLAMA_ALIAS:-local}
|
|
28
|
+
- --ctx-size
|
|
29
|
+
- "${LLAMA_CTX:-8192}"
|
|
30
|
+
# Fils de calcul : le nombre de cœurs PHYSIQUES, pas de vCPU.
|
|
31
|
+
- --threads
|
|
32
|
+
- "${LLAMA_THREADS:-4}"
|
|
33
|
+
# Requêtes simultanées ; le contexte est partagé entre elles (ctx-size / parallel chacune).
|
|
34
|
+
- --parallel
|
|
35
|
+
- "${LLAMA_PARALLEL:-2}"
|
|
36
|
+
- --metrics
|
|
37
|
+
healthcheck:
|
|
38
|
+
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
|
|
39
|
+
interval: 30s
|
|
40
|
+
timeout: 5s
|
|
41
|
+
retries: 5
|
|
42
|
+
# Le chargement d'un modèle de plusieurs Go prend du temps.
|
|
43
|
+
start_period: 120s
|
|
44
|
+
deploy:
|
|
45
|
+
resources:
|
|
46
|
+
limits:
|
|
47
|
+
memory: ${LLAMA_MEMORY_LIMIT:-6g}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/ai",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.0",
|
|
4
4
|
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=20"
|
|
@@ -9,7 +9,8 @@
|
|
|
9
9
|
"types": "src/index.d.ts",
|
|
10
10
|
"type": "commonjs",
|
|
11
11
|
"files": [
|
|
12
|
-
"src"
|
|
12
|
+
"src",
|
|
13
|
+
"deploy"
|
|
13
14
|
],
|
|
14
15
|
"scripts": {
|
|
15
16
|
"test": "jest"
|
|
@@ -22,7 +23,9 @@
|
|
|
22
23
|
"keywords": [
|
|
23
24
|
"astratra",
|
|
24
25
|
"ai",
|
|
25
|
-
"agents"
|
|
26
|
+
"agents",
|
|
27
|
+
"llama.cpp",
|
|
28
|
+
"cpu-inference"
|
|
26
29
|
],
|
|
27
30
|
"license": "MIT",
|
|
28
31
|
"publishConfig": {
|
|
@@ -40,7 +43,7 @@
|
|
|
40
43
|
}
|
|
41
44
|
},
|
|
42
45
|
"devDependencies": {
|
|
43
|
-
"@astratra/resilience": "^0.
|
|
46
|
+
"@astratra/resilience": "^1.0.0",
|
|
44
47
|
"jest": "30.4.2",
|
|
45
48
|
"redis": "^4.7.0"
|
|
46
49
|
}
|
package/src/agentLoop.js
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
const { AppError } = require('@astratra/core');
|
|
2
2
|
|
|
3
3
|
const DEFAULT_MAX_STEPS = 5;
|
|
4
|
+
const DEFAULT_LOOP_THRESHOLDS = Object.freeze({ reminder: 3, firmReminder: 5, stop: 8 });
|
|
5
|
+
const DEFAULT_SPILL_THRESHOLD = 12_000;
|
|
6
|
+
const SPILL_TOOL_NAME = 'read_spilled_result';
|
|
4
7
|
|
|
5
8
|
async function runAgentLoop({
|
|
6
9
|
prompt,
|
|
@@ -17,6 +20,12 @@ async function runAgentLoop({
|
|
|
17
20
|
toolTimeoutMs,
|
|
18
21
|
maxMs,
|
|
19
22
|
finalInstruction,
|
|
23
|
+
loopGuard = {},
|
|
24
|
+
spill = {},
|
|
25
|
+
confirmationPolicy,
|
|
26
|
+
riskAnalyzers = [],
|
|
27
|
+
pendingActions,
|
|
28
|
+
onEvent,
|
|
20
29
|
now = Date.now
|
|
21
30
|
}) {
|
|
22
31
|
if (!registry) throw new AppError('agentLoop requires a registry', 500);
|
|
@@ -26,6 +35,12 @@ async function runAgentLoop({
|
|
|
26
35
|
}
|
|
27
36
|
|
|
28
37
|
const messages = Array.isArray(history) ? [...history] : [];
|
|
38
|
+
const loopCounts = new Map();
|
|
39
|
+
const spillStore = spill.store || createMemorySpillStore();
|
|
40
|
+
const spillThreshold = Number.isFinite(spill.threshold) && spill.threshold >= 0 ? spill.threshold : DEFAULT_SPILL_THRESHOLD;
|
|
41
|
+
const thresholds = { ...DEFAULT_LOOP_THRESHOLDS, ...loopGuard };
|
|
42
|
+
const spills = new Map();
|
|
43
|
+
if (typeof spillStore.set !== 'function' || typeof spillStore.get !== 'function') throw new AppError('spill.store requires set() and get()', 500);
|
|
29
44
|
messages.push({ role: 'user', content: prompt });
|
|
30
45
|
const started = now();
|
|
31
46
|
|
|
@@ -53,13 +68,28 @@ async function runAgentLoop({
|
|
|
53
68
|
const outOfTime = () => Number.isFinite(maxMs) && now() - started >= maxMs;
|
|
54
69
|
|
|
55
70
|
for (let step = 0; step < maxSteps && !outOfTime(); step += 1) {
|
|
56
|
-
const
|
|
71
|
+
const spillInstruction = spills.size ? `\n### Lire un résultat mis de côté\nAppelle <tool_call name="${SPILL_TOOL_NAME}">{"id":"référence","start":0,"length":4000}</tool_call> pour relire une tranche.` : '';
|
|
72
|
+
const response = await askModel(buildPrompt(registry, userRole, messages) + spillInstruction);
|
|
57
73
|
const toolCall = parseToolCall(response);
|
|
58
74
|
|
|
59
75
|
if (!toolCall) {
|
|
60
76
|
return response;
|
|
61
77
|
}
|
|
62
78
|
|
|
79
|
+
if (toolCall.name === SPILL_TOOL_NAME) {
|
|
80
|
+
const id = String(toolCall.params.id || '');
|
|
81
|
+
const stored = spills.get(id);
|
|
82
|
+
let result;
|
|
83
|
+
if (!stored) result = { error: 'spill_not_found' };
|
|
84
|
+
else {
|
|
85
|
+
const start = Math.max(0, Math.floor(Number(toolCall.params.start) || 0));
|
|
86
|
+
const length = Math.min(12_000, Math.max(0, Math.floor(Number(toolCall.params.length) || 4000)));
|
|
87
|
+
const value = await spillStore.get(id);
|
|
88
|
+
result = typeof value === 'string' ? { id, start, totalLength: value.length, text: value.slice(start, start + length) } : { error: 'spill_not_found' };
|
|
89
|
+
}
|
|
90
|
+
messages.push({ role: 'assistant', content: response }, { role: 'tool', content: `<tool_result name="${SPILL_TOOL_NAME}">${JSON.stringify(result)}</tool_result>` });
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
63
93
|
const tool = registry.getToolByName(toolCall.name);
|
|
64
94
|
if (!tool) {
|
|
65
95
|
throw new AppError(`Tool "${toolCall.name}" is not registered`, 400);
|
|
@@ -73,8 +103,41 @@ async function runAgentLoop({
|
|
|
73
103
|
// runs. Denying doesn't crash the loop: the model gets told and can
|
|
74
104
|
// adjust course (ask something else, explain, stop), same as it would
|
|
75
105
|
// handle any other tool result.
|
|
76
|
-
|
|
77
|
-
|
|
106
|
+
const normalizedCall = `${tool.name}:${stableStringify(toolCall.params)}`;
|
|
107
|
+
const repetitions = (loopCounts.get(normalizedCall) || 0) + 1;
|
|
108
|
+
loopCounts.set(normalizedCall, repetitions);
|
|
109
|
+
if (repetitions >= thresholds.stop) {
|
|
110
|
+
const reason = `Boucle arrêtée : l'appel ${tool.name} a été répété ${repetitions} fois.`;
|
|
111
|
+
const event = { type: 'tool_loop_stopped', name: tool.name, repetitions, reason };
|
|
112
|
+
if (typeof onEvent === 'function') onEvent(event);
|
|
113
|
+
return reason;
|
|
114
|
+
}
|
|
115
|
+
if (repetitions === thresholds.reminder || repetitions === thresholds.firmReminder) {
|
|
116
|
+
const reminder = repetitions === thresholds.reminder
|
|
117
|
+
? `Rappel : cet appel identique a déjà été effectué ${repetitions} fois. Change de stratégie si le résultat ne suffit pas.`
|
|
118
|
+
: `Rappel ferme : cet appel identique a déjà été effectué ${repetitions} fois. Ne le répète plus sans modifier les arguments.`;
|
|
119
|
+
messages.push({ role: 'system', content: reminder });
|
|
120
|
+
if (typeof onEvent === 'function') onEvent({ type: 'tool_loop_warning', name: tool.name, repetitions, message: reminder });
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
let requiresConfirmation = typeof confirmTool === 'function';
|
|
124
|
+
if (confirmationPolicy !== undefined) {
|
|
125
|
+
let risk = tool.risk || 'UNKNOWN';
|
|
126
|
+
for (const analyze of riskAnalyzers) {
|
|
127
|
+
const analyzed = await analyze(toolCall, ctx, tool);
|
|
128
|
+
if (analyzed !== undefined && riskValue(analyzed) > riskValue(risk)) risk = String(analyzed).toUpperCase();
|
|
129
|
+
}
|
|
130
|
+
requiresConfirmation = shouldConfirm(confirmationPolicy, risk);
|
|
131
|
+
}
|
|
132
|
+
if (requiresConfirmation) {
|
|
133
|
+
let approved;
|
|
134
|
+
if (typeof confirmTool === 'function') approved = await confirmTool(toolCall, ctx);
|
|
135
|
+
else if (pendingActions && typeof pendingActions.propose === 'function') {
|
|
136
|
+
const proposed = await pendingActions.propose({ action: tool.name, payload: toolCall.params, description: `Appel ${tool.name} (${tool.risk || 'UNKNOWN'})`, proposedBy: ctx.userId, tenant: ctx.tenantId });
|
|
137
|
+
approved = false;
|
|
138
|
+
messages.push({ role: 'assistant', content: response }, { role: 'tool', content: `<tool_result name="${tool.name}">${JSON.stringify({ pending: true, actionId: proposed.action.id })}</tool_result>` });
|
|
139
|
+
continue;
|
|
140
|
+
} else approved = false;
|
|
78
141
|
if (!approved) {
|
|
79
142
|
messages.push({ role: 'assistant', content: response });
|
|
80
143
|
messages.push({
|
|
@@ -100,13 +163,25 @@ async function runAgentLoop({
|
|
|
100
163
|
}
|
|
101
164
|
if (masker && tool.external === true) result = masker.unmaskDeep(result);
|
|
102
165
|
const serialized = JSON.stringify(result);
|
|
166
|
+
const modelSerialized = masker ? masker.mask(serialized) : serialized;
|
|
103
167
|
/* Your own data (a class list, a file) carries names the register may not
|
|
104
168
|
know: the detector reads the result before it can reach the prompt. */
|
|
105
169
|
if (masker && tool.external !== true && typeof masker.maskAsync === 'function') await masker.maskAsync(String(serialized));
|
|
106
170
|
messages.push({ role: 'assistant', content: response });
|
|
171
|
+
let modelResult = serialized;
|
|
172
|
+
if (serialized.length > spillThreshold) {
|
|
173
|
+
const id = createSpillId();
|
|
174
|
+
try {
|
|
175
|
+
await spillStore.set(id, serialized);
|
|
176
|
+
spills.set(id, true);
|
|
177
|
+
modelResult = JSON.stringify({ spilled: true, id, totalLength: serialized.length, excerpt: modelSerialized.slice(0, 1500), readTool: SPILL_TOOL_NAME });
|
|
178
|
+
} catch (_error) {
|
|
179
|
+
modelResult = JSON.stringify({ error: 'result_storage_failed' });
|
|
180
|
+
}
|
|
181
|
+
}
|
|
107
182
|
messages.push({
|
|
108
183
|
role: 'tool',
|
|
109
|
-
content: `<tool_result name="${tool.name}">${
|
|
184
|
+
content: `<tool_result name="${tool.name}">${modelResult}</tool_result>`
|
|
110
185
|
});
|
|
111
186
|
}
|
|
112
187
|
|
|
@@ -121,6 +196,24 @@ async function runAgentLoop({
|
|
|
121
196
|
throw new AppError(`agentLoop reached maxSteps (${maxSteps}) before a final answer`, 500);
|
|
122
197
|
}
|
|
123
198
|
|
|
199
|
+
function stableStringify(value) {
|
|
200
|
+
if (value === null || typeof value !== 'object') return JSON.stringify(value);
|
|
201
|
+
if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
|
|
202
|
+
return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
|
|
203
|
+
}
|
|
204
|
+
function riskValue(risk) { return ({ LOW: 0, MEDIUM: 1, HIGH: 2, UNKNOWN: 3 })[String(risk).toUpperCase()] ?? 3; }
|
|
205
|
+
function shouldConfirm(policy, risk) {
|
|
206
|
+
if (policy === 'always') return true;
|
|
207
|
+
if (policy === 'never') return false;
|
|
208
|
+
const threshold = typeof policy === 'object' && policy ? policy.threshold : policy;
|
|
209
|
+
return risk === 'UNKNOWN' || riskValue(risk) >= riskValue(threshold);
|
|
210
|
+
}
|
|
211
|
+
function createMemorySpillStore() {
|
|
212
|
+
const values = new Map();
|
|
213
|
+
return { async set(id, value) { values.set(id, value); }, async get(id) { return values.get(id); } };
|
|
214
|
+
}
|
|
215
|
+
function createSpillId() { return `spill_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`; }
|
|
216
|
+
|
|
124
217
|
async function runTool(tool, params, ctx, timeoutMs) {
|
|
125
218
|
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return tool.handler(params, ctx);
|
|
126
219
|
let timer;
|
|
@@ -200,5 +293,8 @@ function estimateTokens(text) {
|
|
|
200
293
|
}
|
|
201
294
|
|
|
202
295
|
module.exports = {
|
|
203
|
-
runAgentLoop
|
|
296
|
+
runAgentLoop,
|
|
297
|
+
createMemorySpillStore,
|
|
298
|
+
DEFAULT_LOOP_THRESHOLDS,
|
|
299
|
+
DEFAULT_SPILL_THRESHOLD
|
|
204
300
|
};
|
package/src/answerText.js
CHANGED
|
@@ -33,6 +33,8 @@ function plainText(text) {
|
|
|
33
33
|
* @param {string} text
|
|
34
34
|
* @param {object} [options]
|
|
35
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.
|
|
36
38
|
*/
|
|
37
39
|
function tidyMarkdown(text, options = {}) {
|
|
38
40
|
let out = String(text === null || text === undefined ? '' : text)
|
|
@@ -49,6 +51,10 @@ function tidyMarkdown(text, options = {}) {
|
|
|
49
51
|
.replace(/(^|[^*])\*(?!\*)/g, '$1')
|
|
50
52
|
.replace(/`([^`]+)`/g, '$1')
|
|
51
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
|
+
}
|
|
52
58
|
if (options.removeEmoji) {
|
|
53
59
|
out = out.replace(/[\p{Extended_Pictographic}\p{Emoji_Modifier}\u{FE0F}\u{200D}]/gu, '');
|
|
54
60
|
}
|
|
@@ -59,6 +65,20 @@ function tidyMarkdown(text, options = {}) {
|
|
|
59
65
|
.trim();
|
|
60
66
|
}
|
|
61
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
|
+
|
|
62
82
|
/* A quotation between guillemets, curly quotes or straight quotes. */
|
|
63
83
|
const QUOTATION = /(«\s*)([^«»]+?)(\s*»)|(“)([^“”]+)(”)|(")([^"\n]+)(")/g;
|
|
64
84
|
/* What may stand between a quotation and the reference saying where it comes from. */
|
|
@@ -114,4 +134,4 @@ async function verifyQuotations(text, options = {}) {
|
|
|
114
134
|
return out;
|
|
115
135
|
}
|
|
116
136
|
|
|
117
|
-
module.exports = { plainText, tidyMarkdown, verifyQuotations, isFaithfulQuotation };
|
|
137
|
+
module.exports = { plainText, tidyMarkdown, verifyQuotations, isFaithfulQuotation, wholeSentences };
|
package/src/askLimit.js
CHANGED
|
@@ -17,6 +17,8 @@ const { AppError } = require('@astratra/core');
|
|
|
17
17
|
* @param {number} options.windowMs
|
|
18
18
|
* @param {string} [options.code] Default 'AI_RATE_LIMITED'.
|
|
19
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.
|
|
20
22
|
*/
|
|
21
23
|
function createAskLimit(options = {}) {
|
|
22
24
|
const { max, windowMs } = options;
|
|
@@ -26,6 +28,7 @@ function createAskLimit(options = {}) {
|
|
|
26
28
|
const sweepEvery = options.sweepEvery || 500;
|
|
27
29
|
const asks = new Map();
|
|
28
30
|
let sinceSweep = 0;
|
|
31
|
+
let sweptAt = -Infinity;
|
|
29
32
|
|
|
30
33
|
function sweep(now) {
|
|
31
34
|
for (const [id, times] of asks) {
|
|
@@ -33,6 +36,7 @@ function createAskLimit(options = {}) {
|
|
|
33
36
|
if (recent.length) asks.set(id, recent);
|
|
34
37
|
else asks.delete(id);
|
|
35
38
|
}
|
|
39
|
+
sweptAt = now;
|
|
36
40
|
}
|
|
37
41
|
|
|
38
42
|
/** What `take` would answer, without counting an ask. */
|
|
@@ -46,7 +50,7 @@ function createAskLimit(options = {}) {
|
|
|
46
50
|
function take(subject, now = Date.now()) {
|
|
47
51
|
const id = String(subject);
|
|
48
52
|
sinceSweep += 1;
|
|
49
|
-
if (sinceSweep >= sweepEvery) {
|
|
53
|
+
if (sinceSweep >= sweepEvery || now - sweptAt >= windowMs) {
|
|
50
54
|
sinceSweep = 0;
|
|
51
55
|
sweep(now);
|
|
52
56
|
}
|