@astratra/ai 1.7.0 → 1.9.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 +1 -1
- package/README.md +116 -8
- package/guards/package.json +4 -0
- package/guards/testing/package.json +4 -0
- package/package.json +29 -6
- package/src/gemini.js +107 -15
- package/src/guards/createGuards.js +456 -0
- package/src/guards/frame.js +36 -0
- package/src/guards/index.d.ts +150 -0
- package/src/guards/index.js +16 -0
- package/src/guards/leaks.js +63 -0
- package/src/guards/recommended.js +31 -0
- package/src/guards/testing/index.d.ts +30 -0
- package/src/guards/testing/index.js +116 -0
- package/src/index.d.ts +39 -1
- package/src/masking.js +34 -1
- package/src/modelAnswers.js +8 -1
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -6,12 +6,75 @@ 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. Le routeur
|
|
8
8
|
configuré, les clients de modèles locaux et les services vocaux ci-dessous
|
|
9
|
-
partagent désormais les mécanismes utilisés par
|
|
9
|
+
partagent désormais les mécanismes utilisés par deux assistants d'IA en production. Ce
|
|
10
10
|
qu'il fournit, c'est le mécanisme durement acquis : suivi de quota, ordre de
|
|
11
11
|
fallback, cooldown/dégradation, deux adaptateurs HTTP sans dépendance (le
|
|
12
12
|
format OpenAI et Gemini), et deux boucles d'agent (protocole écrit, ou
|
|
13
13
|
appels d'outils natifs).
|
|
14
14
|
|
|
15
|
+
## Gardes d'agent / Agent guards (`@astratra/ai/guards`)
|
|
16
|
+
|
|
17
|
+
Protections prêtes à brancher sur un agent, indépendantes du fournisseur d'IA.
|
|
18
|
+
Elles s'appuient sur le client de `@astratra/models` **injecté** (`models`) :
|
|
19
|
+
aucune dépendance dure. `@astratra/rag` (`verifySources`) est une dépendance
|
|
20
|
+
de pair facultative, ou s'injecte avec l'option `verifySources`.
|
|
21
|
+
|
|
22
|
+
```js
|
|
23
|
+
const { recommendedGuards } = require('@astratra/ai/guards');
|
|
24
|
+
const { createModelsClient, assertModelsReady } = require('@astratra/models');
|
|
25
|
+
|
|
26
|
+
assertModelsReady({ required: ['entities', 'injection', 'moderation', 'nli'] }); // en production, refuse de partir sans les modèles
|
|
27
|
+
const guards = recommendedGuards({ models: createModelsClient({ token: () => process.env.MODELS_TOKEN }), onEvent: log });
|
|
28
|
+
|
|
29
|
+
const run = guards.newRun(); // une par conversation ou exécution d'agent
|
|
30
|
+
const safe = await guards.input(question, run); // noms et données personnelles masqués, réversible
|
|
31
|
+
if (safe.decision === 'block') return refuse();
|
|
32
|
+
// ... l'agent appelle ses outils ...
|
|
33
|
+
const seen = await guards.toolResult(page, run, { tool: 'web_search', external: true });
|
|
34
|
+
messages.push({ role: 'tool', content: seen.content }); // masqué, encadré comme donnée non fiable
|
|
35
|
+
const action = await guards.beforeAction({ name: 'send_email' }, run);
|
|
36
|
+
if (action.decision === 'block') askAHuman(); // après une injection suspectée : jamais sans humain
|
|
37
|
+
const reply = await guards.output(modelAnswer, run); // démasqué, puis ancrage, fuite, modération
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| Garde | Ce qu'elle fait |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `input(text, run)` | masque les noms (détecteur d'entités + `names` du registre) et les données structurées (e-mail, IBAN, carte, téléphone) ; le texte revient démasqué dans `output`. Rend `text: null` si elle bloque. |
|
|
43
|
+
| `toolResult(result, run, { tool, external })` | pour un résultat **externe** (ou marqué `{ untrusted: true, content }`) : détection d'injection (texte long lu par fenêtres, jamais passé sans contrôle), contenu encadré par des marqueurs à nonce comme *données non fiables*. Injection suspectée : `run.requiresConfirmation = true` pour tout le reste de l'exécution. |
|
|
44
|
+
| `output(text, run)` | démasque ; **ancrage** (chaque phrase contre les sources lues, NLI, via `verifySources` de rag) avec `groundingScore` et la liste `unsupported` ; **fuite** de données personnelles que la personne n'a pas données (`onLeak`: `block`, `redact`, `flag`) ; **modération**. |
|
|
45
|
+
| `beforeAction(action, run, { humanConfirmed })` | refuse toute action tant qu'une injection est suspectée et qu'aucun humain n'a confirmé (`humanConfirmed: true` vient de votre interface, jamais du modèle). |
|
|
46
|
+
|
|
47
|
+
**Panne** : `policy.failure = { action: 'failClosed', read: 'failClosed' }` par
|
|
48
|
+
défaut (bloquer et signaler). `failOpen` laisse passer en signalant
|
|
49
|
+
`degraded` ; `recommendedGuards({ readOnly: true })` l'applique à un agent qui
|
|
50
|
+
ne fait que lire. Le mode d'une exécution est `newRun({ mode: 'action' | 'read' })`.
|
|
51
|
+
|
|
52
|
+
**Événements** : chaque décision appelle `onEvent({ type: 'guard', guard, decision,
|
|
53
|
+
reasons, degraded, metrics, runId, mode, at })`. Ils ne contiennent jamais le
|
|
54
|
+
texte (ni saisie, ni résultat d'outil, ni réponse) : des nombres, des codes et
|
|
55
|
+
des noms de catégories. La réponse de `output` rend, elle, les phrases non
|
|
56
|
+
soutenues à l'appelant.
|
|
57
|
+
|
|
58
|
+
**Tests** : `@astratra/ai/guards/testing` fournit `createFakeModels` (un client
|
|
59
|
+
sans modèle : règles par mots-clés, pannes simulées), `createMockGuards` (les
|
|
60
|
+
vraies gardes sur ce client, avec un enregistreur d'événements) et
|
|
61
|
+
`createEventRecorder`.
|
|
62
|
+
|
|
63
|
+
Limites : les gardes réduisent le risque, elles ne le suppriment pas. Les
|
|
64
|
+
règles de fuite ne couvrent que les données structurées ; l'ancrage compte
|
|
65
|
+
aussi comme « non soutenues » des phrases de liaison ; la détection d'injection
|
|
66
|
+
lit un texte isolé.
|
|
67
|
+
|
|
68
|
+
English: ready-to-use guards for an agent, independent of the AI provider.
|
|
69
|
+
Inject the `@astratra/models` client as `models`; nothing is imported. `input`
|
|
70
|
+
masks names and personal data (reversible), `toolResult` scans untrusted
|
|
71
|
+
content for injection, frames it as untrusted data and, when an injection is
|
|
72
|
+
suspected, forbids every action without a human for the rest of the run
|
|
73
|
+
(`beforeAction`), `output` unmasks the reply and checks grounding against the
|
|
74
|
+
sources, personal-data leaks and moderation. Failure policy is `failClosed` for
|
|
75
|
+
actions by default, `failOpen` possible for read-only runs. Events never carry
|
|
76
|
+
the text. Mocks for tests: `@astratra/ai/guards/testing`.
|
|
77
|
+
|
|
15
78
|
## Routeur de providers
|
|
16
79
|
|
|
17
80
|
```js
|
|
@@ -114,6 +177,37 @@ appel — et n'est jamais une réponse à montrer. Des arguments illisibles gard
|
|
|
114
177
|
l'appel, marqué `invalid` avec `invalidReason` (`not_json`, `not_object`), et
|
|
115
178
|
repartent en `{}` au tour suivant.
|
|
116
179
|
|
|
180
|
+
### La recherche Google intégrée de Gemini
|
|
181
|
+
|
|
182
|
+
`googleSearch` sur une requête active l'outil de recherche de Gemini
|
|
183
|
+
(`google_search` dans generateContent). Les fournisseurs au format OpenAI
|
|
184
|
+
l'ignorent. Le fournisseur `detailed` rend alors `grounding` : les recherches
|
|
185
|
+
faites et les pages citées, sous une forme stable.
|
|
186
|
+
|
|
187
|
+
```js
|
|
188
|
+
const { value } = await router.route({
|
|
189
|
+
system, messages, tools,
|
|
190
|
+
googleSearch: true // ou { functions: 'auto' | 'combine' | 'alone' }
|
|
191
|
+
});
|
|
192
|
+
// value.grounding = { searched, queries: ['…'], sources: [{ title, url }],
|
|
193
|
+
// searchSuggestionsHtml, functionsDropped }
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Avec les fonctions de l'application : `combine` envoie les deux outils
|
|
197
|
+
ensemble ; `alone` n'envoie que la recherche pour ce tour (aucun appel de
|
|
198
|
+
fonction n'est lu) ; `auto` (défaut) les envoie ensemble et, si l'API refuse le
|
|
199
|
+
mélange (400), redemande avec la recherche seule — `functionsDropped: true` le
|
|
200
|
+
dit. Selon le modèle, l'API accepte ou non le mélange : `auto` couvre les deux.
|
|
201
|
+
|
|
202
|
+
Les pages lues sont des **données non fiables**. Le paquet n'en rend que des
|
|
203
|
+
titres (une ligne, 200 caractères au plus, caractères de contrôle retirés) et
|
|
204
|
+
des adresses `http(s)` sans identifiants, dédoublonnées (20 pages, 10 recherches
|
|
205
|
+
au plus) ; il ne les relit jamais comme des consignes et ne les remet jamais
|
|
206
|
+
dans un message. `readGeminiGrounding(réponse)` fait la même lecture sur une
|
|
207
|
+
réponse brute. Google demande d'afficher ses suggestions de recherche avec une
|
|
208
|
+
réponse sourcée : `searchSuggestionsHtml` les rend telles quelles, à afficher
|
|
209
|
+
dans un cadre isolé.
|
|
210
|
+
|
|
117
211
|
## Outils natifs : la boucle d'un agent qui appelle ses outils
|
|
118
212
|
|
|
119
213
|
```js
|
|
@@ -631,7 +725,7 @@ là où un tableau tenait, se tromper vers le grand coûte un tableau illisible.
|
|
|
631
725
|
La règle `paragraphs` est **obligatoire** : un pack de langue qui ne l'a pas est
|
|
632
726
|
refusé à la création, pas découvert sur un écran.
|
|
633
727
|
|
|
634
|
-
## Configured routing (
|
|
728
|
+
## Configured routing (two production assistants)
|
|
635
729
|
|
|
636
730
|
`createConfiguredRouter` builds HTTP providers and routes by usage on top of
|
|
637
731
|
`createProviderRouter`. Existing exports and their defaults remain compatible.
|
|
@@ -685,12 +779,12 @@ router.stop(); // rejects subsequent calls; no owned DB c
|
|
|
685
779
|
|
|
686
780
|
Without `usage`, tools select `tools`, images select `vision`, explicit `json:
|
|
687
781
|
true` selects `json`, simple requests select `quick`, and the rest selects
|
|
688
|
-
`chat`. `estimateRequestComplexity` retains
|
|
782
|
+
`chat`. `estimateRequestComplexity` retains the word/keyword rules of the reference assistant (with
|
|
689
783
|
English equivalents); you can override `complexity`. Within a list, intent
|
|
690
784
|
preferences come first, then compatible complexity, then other models; preview
|
|
691
785
|
models come last. Without a usage list, provider/model declaration order is the
|
|
692
|
-
fallback order. Thus
|
|
693
|
-
|
|
786
|
+
fallback order. Thus one assistant's Groq → Mistral → Gemini → Vercel → Ollama and
|
|
787
|
+
another assistant's distinct quick/chat/pilot orders are both expressible.
|
|
694
788
|
|
|
695
789
|
Model fields: `vision`, `visionOnly`, `complexity`, `extra`, `maxTokens`,
|
|
696
790
|
`maxInputTokens`, `noAnalytics`, `languages`, `preview`, `disabled`, `rpm`, `rpd`,
|
|
@@ -743,6 +837,20 @@ Errors have clean codes: `AI_NO_PROVIDER`, `AI_NO_MATCH`, `AI_UNAVAILABLE`,
|
|
|
743
837
|
silently losing a distributed quota. Transport messages and credentials are
|
|
744
838
|
not included in these errors.
|
|
745
839
|
|
|
840
|
+
### Gemini Google Search grounding
|
|
841
|
+
|
|
842
|
+
Set `googleSearch` on a request to enable Gemini's built-in search tool
|
|
843
|
+
(`google_search`). OpenAI-format providers ignore it. A `detailed` Gemini
|
|
844
|
+
provider then returns `grounding: { searched, queries, sources: [{ title, url }],
|
|
845
|
+
searchSuggestionsHtml, functionsDropped }`. With application functions,
|
|
846
|
+
`combine` sends both tools, `alone` sends only search for that turn, and `auto`
|
|
847
|
+
(default) sends both and retries with search alone when the API rejects the
|
|
848
|
+
combination (HTTP 400). Pages are untrusted data: only cleaned single-line
|
|
849
|
+
titles and credential-free `http(s)` URLs are returned (at most 20 sources and
|
|
850
|
+
10 queries); nothing from a page is ever treated as an instruction.
|
|
851
|
+
`readGeminiGrounding(response)` reads a raw generateContent response the same
|
|
852
|
+
way.
|
|
853
|
+
|
|
746
854
|
### Injectable state: memory, Redis, PostgreSQL
|
|
747
855
|
|
|
748
856
|
```js
|
|
@@ -792,7 +900,7 @@ object, never an `.env` file. `ARIA_` or another prefix works identically.
|
|
|
792
900
|
| `IA_WAITED_TIMEOUT_MS`, `IA_BACKGROUND_TIMEOUT_MS` | Defaults 12000/45000 |
|
|
793
901
|
| `IA_COOLDOWN_MS`, `IA_DEGRADED_MS`, `IA_MAX_FAILURES` | Defaults 120000/300000/3 |
|
|
794
902
|
| `IA_STATE_PREFIX`, `IA_WHEN_ALL_COOLING`, `IA_RESERVE_VISION` | Namespace, skip/try, true/false |
|
|
795
|
-
| `IA_MODELS_URL`, `IA_MODELS_TOKEN_FILE` | Optional
|
|
903
|
+
| `IA_MODELS_URL`, `IA_MODELS_TOKEN_FILE` | Optional local model server and its Bearer file |
|
|
796
904
|
| `IA_TTS_URL`, `IA_TTS_TOKEN_FILE` | Optional Piper server and Bearer file |
|
|
797
905
|
| `IA_LANGUAGE_URL`, `IA_LANGUAGE_TIMEOUT_MS` | Optional fastText server; default timeout 800 |
|
|
798
906
|
| `IA_GROQ_WHISPER_URL`, `IA_GROQ_WHISPER_MODELS` | Full endpoint, JSON model IDs; defaults Groq transcription endpoint and turbo/large-v3 |
|
|
@@ -813,7 +921,7 @@ const config = readAiConfigFromEnv({ prefix: 'ARIA_' });
|
|
|
813
921
|
const router = createConfiguredRouter({ ...config, store });
|
|
814
922
|
```
|
|
815
923
|
|
|
816
|
-
## Local models (
|
|
924
|
+
## Local models (HTTP protocol)
|
|
817
925
|
|
|
818
926
|
```js
|
|
819
927
|
const { createLocalModelsClient } = require('@astratra/ai');
|
|
@@ -844,7 +952,7 @@ authentication header is sent. The server receives `X-Delai-Ms`. Defaults per
|
|
|
844
952
|
route: rerank 1000ms, NLI/vector 1500ms, entities 800ms, transcription 15000ms.
|
|
845
953
|
Each route has its own three-failure/60-second circuit, with one recovery probe;
|
|
846
954
|
4xx refusals do not open it. Python engines, ONNX runtimes and weights are not
|
|
847
|
-
bundled or downloaded by this client.
|
|
955
|
+
bundled or downloaded by this client. A generic in-process embedding
|
|
848
956
|
and native voice primitives remain in `@astratra/rag` and `@astratra/voice`.
|
|
849
957
|
|
|
850
958
|
## Transcription, speech and language
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/ai",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
|
|
3
|
+
"version": "1.9.0",
|
|
4
|
+
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra, plus agent guards (@astratra/ai/guards): outbound masking, prompt-injection handling for untrusted tool results, reply checks.",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=20"
|
|
7
7
|
},
|
|
@@ -10,7 +10,8 @@
|
|
|
10
10
|
"type": "commonjs",
|
|
11
11
|
"files": [
|
|
12
12
|
"src",
|
|
13
|
-
"deploy"
|
|
13
|
+
"deploy",
|
|
14
|
+
"guards"
|
|
14
15
|
],
|
|
15
16
|
"scripts": {
|
|
16
17
|
"test": "jest"
|
|
@@ -25,7 +26,9 @@
|
|
|
25
26
|
"ai",
|
|
26
27
|
"agents",
|
|
27
28
|
"llama.cpp",
|
|
28
|
-
"cpu-inference"
|
|
29
|
+
"cpu-inference",
|
|
30
|
+
"guardrails",
|
|
31
|
+
"prompt-injection"
|
|
29
32
|
],
|
|
30
33
|
"license": "MIT",
|
|
31
34
|
"publishConfig": {
|
|
@@ -35,16 +38,36 @@
|
|
|
35
38
|
"@astratra/core": "^1.0.0"
|
|
36
39
|
},
|
|
37
40
|
"peerDependencies": {
|
|
38
|
-
"redis": ">=4"
|
|
41
|
+
"redis": ">=4",
|
|
42
|
+
"@astratra/rag": ">=1.0.0"
|
|
39
43
|
},
|
|
40
44
|
"peerDependenciesMeta": {
|
|
41
45
|
"redis": {
|
|
42
46
|
"optional": true
|
|
47
|
+
},
|
|
48
|
+
"@astratra/rag": {
|
|
49
|
+
"optional": true
|
|
43
50
|
}
|
|
44
51
|
},
|
|
45
52
|
"devDependencies": {
|
|
46
53
|
"@astratra/resilience": "^1.0.0",
|
|
47
54
|
"jest": "30.4.2",
|
|
48
|
-
"redis": "^4.7.0"
|
|
55
|
+
"redis": "^4.7.0",
|
|
56
|
+
"@astratra/rag": "^1.0.0"
|
|
57
|
+
},
|
|
58
|
+
"exports": {
|
|
59
|
+
".": {
|
|
60
|
+
"types": "./src/index.d.ts",
|
|
61
|
+
"default": "./src/index.js"
|
|
62
|
+
},
|
|
63
|
+
"./guards": {
|
|
64
|
+
"types": "./src/guards/index.d.ts",
|
|
65
|
+
"default": "./src/guards/index.js"
|
|
66
|
+
},
|
|
67
|
+
"./guards/testing": {
|
|
68
|
+
"types": "./src/guards/testing/index.d.ts",
|
|
69
|
+
"default": "./src/guards/testing/index.js"
|
|
70
|
+
},
|
|
71
|
+
"./package.json": "./package.json"
|
|
49
72
|
}
|
|
50
73
|
}
|
package/src/gemini.js
CHANGED
|
@@ -13,7 +13,11 @@ const { readRetryAfter } = require('./providerLimits');
|
|
|
13
13
|
* - une réponse arrêtée à sa longueur (MAX_TOKENS) le dit (`cut`), pour que le
|
|
14
14
|
* routeur la garde en dernier recours seulement ;
|
|
15
15
|
* - la clé part dans l'en-tête, jamais dans l'adresse (où elle finirait dans
|
|
16
|
-
* les journaux)
|
|
16
|
+
* les journaux) ;
|
|
17
|
+
* - la recherche Google intégrée (`googleSearch` sur la requête) rend ses
|
|
18
|
+
* sources sous une forme stable (`grounding`) ; les pages lues sont des
|
|
19
|
+
* DONNÉES NON FIABLES : rien ici ne les relit comme des consignes, seuls
|
|
20
|
+
* des titres et des adresses http(s) nettoyés sont rendus.
|
|
17
21
|
*/
|
|
18
22
|
|
|
19
23
|
const { providerResult, readWrittenAnswer, withoutThinking } = require('./modelAnswers');
|
|
@@ -43,14 +47,90 @@ function contentsOf(messages) {
|
|
|
43
47
|
});
|
|
44
48
|
}
|
|
45
49
|
|
|
50
|
+
/* ─────────── Recherche Google intégrée ─────────── */
|
|
51
|
+
|
|
52
|
+
const SEARCH_FUNCTION_MODES = new Set(['auto', 'combine', 'alone']);
|
|
53
|
+
const MAX_QUERIES = 10;
|
|
54
|
+
const MAX_SOURCES = 20;
|
|
55
|
+
const MAX_QUERY_LENGTH = 300;
|
|
56
|
+
const MAX_TITLE_LENGTH = 200;
|
|
57
|
+
const MAX_URL_LENGTH = 2048;
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* L'option `googleSearch` d'une requête : `true` vaut `{ functions: 'auto' }`.
|
|
61
|
+
* - 'combine' : l'outil de recherche part avec les fonctions de l'application ;
|
|
62
|
+
* - 'alone' : pour ce tour, la recherche seule (les fonctions ne partent pas) ;
|
|
63
|
+
* - 'auto' : d'abord ensemble ; si l'API refuse le mélange (400), une seconde
|
|
64
|
+
* demande part avec la recherche seule.
|
|
65
|
+
*/
|
|
66
|
+
function searchOptions(value) {
|
|
67
|
+
if (!value) return null;
|
|
68
|
+
const functions = value === true ? 'auto' : (value.functions || 'auto');
|
|
69
|
+
if (!SEARCH_FUNCTION_MODES.has(functions)) throw new TypeError('googleSearch.functions must be "auto", "combine" or "alone".');
|
|
70
|
+
return { functions };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/* Une chaîne lue dans une page : caractères de contrôle retirés, espaces resserrés, bornée. */
|
|
74
|
+
function cleanLine(value, max) {
|
|
75
|
+
if (typeof value !== 'string') return '';
|
|
76
|
+
// eslint-disable-next-line no-control-regex
|
|
77
|
+
const line = value.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069]/g, ' ').replace(/\s+/g, ' ').trim();
|
|
78
|
+
return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/* Une adresse http(s) seulement, sans identifiants ; sinon null. */
|
|
82
|
+
function cleanUrl(value) {
|
|
83
|
+
if (typeof value !== 'string' || value.length > MAX_URL_LENGTH) return null;
|
|
84
|
+
let url;
|
|
85
|
+
try {
|
|
86
|
+
url = new URL(value.trim());
|
|
87
|
+
} catch (_error) {
|
|
88
|
+
return null;
|
|
89
|
+
}
|
|
90
|
+
if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.username || url.password) return null;
|
|
91
|
+
return url.href;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Les sources d'une réponse Gemini (`groundingMetadata`) : les recherches faites,
|
|
96
|
+
* et les pages (titre, adresse) dédoublonnées et bornées. Accepte la réponse
|
|
97
|
+
* entière de generateContent ou l'un de ses candidats. Ne lève jamais.
|
|
98
|
+
* @returns {{ searched: boolean, queries: string[], sources: { title: string, url: string }[], searchSuggestionsHtml: string|null }}
|
|
99
|
+
*/
|
|
100
|
+
function readGeminiGrounding(answer) {
|
|
101
|
+
const candidate = answer && Array.isArray(answer.candidates) ? answer.candidates[0] : answer;
|
|
102
|
+
const metadata = (candidate && typeof candidate === 'object' && candidate.groundingMetadata) || {};
|
|
103
|
+
const queries = [];
|
|
104
|
+
for (const raw of Array.isArray(metadata.webSearchQueries) ? metadata.webSearchQueries : []) {
|
|
105
|
+
const query = cleanLine(raw, MAX_QUERY_LENGTH);
|
|
106
|
+
if (query && !queries.includes(query) && queries.length < MAX_QUERIES) queries.push(query);
|
|
107
|
+
}
|
|
108
|
+
const sources = [];
|
|
109
|
+
for (const chunk of Array.isArray(metadata.groundingChunks) ? metadata.groundingChunks : []) {
|
|
110
|
+
const web = chunk && typeof chunk === 'object' ? chunk.web : null;
|
|
111
|
+
const url = web ? cleanUrl(web.uri) : null;
|
|
112
|
+
if (!url || sources.some((source) => source.url === url)) continue;
|
|
113
|
+
const title = cleanLine(web.title, MAX_TITLE_LENGTH) || new URL(url).hostname;
|
|
114
|
+
sources.push({ title, url });
|
|
115
|
+
if (sources.length >= MAX_SOURCES) break;
|
|
116
|
+
}
|
|
117
|
+
const entry = metadata.searchEntryPoint && typeof metadata.searchEntryPoint.renderedContent === 'string'
|
|
118
|
+
? metadata.searchEntryPoint.renderedContent
|
|
119
|
+
: null;
|
|
120
|
+
return { searched: queries.length > 0 || sources.length > 0, queries, sources, searchSuggestionsHtml: entry };
|
|
121
|
+
}
|
|
122
|
+
|
|
46
123
|
/** Le corps de la requête pour un modèle. */
|
|
47
|
-
function requestBody(model, request, noSystemInstruction) {
|
|
124
|
+
function requestBody(model, request, noSystemInstruction, search = null, dropFunctions = false) {
|
|
48
125
|
const contents = contentsOf(request.messages);
|
|
49
126
|
const generationConfig = {
|
|
50
127
|
temperature: request.temperature === undefined ? 0.4 : request.temperature,
|
|
51
128
|
maxOutputTokens: request.maxTokens || 1200
|
|
52
129
|
};
|
|
53
|
-
const
|
|
130
|
+
const toolList = [];
|
|
131
|
+
if (request.tools && request.tools.length && !dropFunctions) toolList.push({ functionDeclarations: request.tools });
|
|
132
|
+
if (search) toolList.push({ google_search: {} });
|
|
133
|
+
const functions = toolList.length ? { tools: toolList } : {};
|
|
54
134
|
const system = request.system || '';
|
|
55
135
|
if (!noSystemInstruction(model)) {
|
|
56
136
|
return { ...(system ? { systemInstruction: { parts: [{ text: system }] } } : {}), contents, generationConfig, ...functions };
|
|
@@ -69,38 +149,50 @@ function requestBody(model, request, noSystemInstruction) {
|
|
|
69
149
|
/**
|
|
70
150
|
* Demande à un modèle Gemini.
|
|
71
151
|
* @param {string} model
|
|
72
|
-
* @param {{ system?: string, messages: object[], tools?: object[], maxTokens?: number, temperature?: number }} request
|
|
152
|
+
* @param {{ system?: string, messages: object[], tools?: object[], maxTokens?: number, temperature?: number, googleSearch?: boolean|{ functions?: 'auto'|'combine'|'alone' } }} request
|
|
73
153
|
* @param {{ key: string, fetch: Function, signal?: AbortSignal, timeoutMs?: number, endpoint?: string, noSystemInstruction?: Function }} io
|
|
74
|
-
* @returns {Promise<{ status: number, text?: string|null, toolCalls?: object[], cut?: boolean }>}
|
|
75
|
-
* Un refus se résout en `{ status }` — rien n'est levé pour lui.
|
|
154
|
+
* @returns {Promise<{ status: number, text?: string|null, toolCalls?: object[], cut?: boolean, grounding?: object }>}
|
|
155
|
+
* Un refus se résout en `{ status }` — rien n'est levé pour lui. Avec
|
|
156
|
+
* `googleSearch`, la réponse porte `grounding` (voir readGeminiGrounding),
|
|
157
|
+
* plus `functionsDropped` : vrai quand les fonctions ne sont pas parties.
|
|
76
158
|
*/
|
|
77
159
|
async function askGeminiModel(model, request, io = {}) {
|
|
78
160
|
if (typeof io.fetch !== 'function') throw new Error('askGeminiModel requires io.fetch.');
|
|
161
|
+
const search = searchOptions(request.googleSearch);
|
|
162
|
+
const hasFunctions = Boolean(request.tools && request.tools.length);
|
|
79
163
|
const timeout = globalThis.AbortSignal.timeout(io.timeoutMs || DEFAULT_TIMEOUT_MS);
|
|
80
164
|
const signal = io.signal ? globalThis.AbortSignal.any([io.signal, timeout]) : timeout;
|
|
81
|
-
const
|
|
165
|
+
const send = (dropFunctions) => io.fetch(`${io.endpoint || DEFAULT_ENDPOINT}/${model}:generateContent`, {
|
|
82
166
|
method: 'POST',
|
|
83
167
|
headers: { 'content-type': 'application/json', 'x-goog-api-key': io.key },
|
|
84
|
-
body: JSON.stringify({ ...requestBody(model, request, io.noSystemInstruction || noSystemInstructionByDefault), ...(io.extra || {}) }),
|
|
168
|
+
body: JSON.stringify({ ...requestBody(model, request, io.noSystemInstruction || noSystemInstructionByDefault, search, dropFunctions), ...(io.extra || {}) }),
|
|
85
169
|
signal
|
|
86
170
|
});
|
|
171
|
+
let functionsDropped = Boolean(search && hasFunctions && search.functions === 'alone');
|
|
172
|
+
let response = await send(functionsDropped);
|
|
173
|
+
/* Le mélange recherche + fonctions refusé par l'API : la recherche seule, pour ce tour. */
|
|
174
|
+
if (!response.ok && response.status === 400 && search && hasFunctions && search.functions === 'auto') {
|
|
175
|
+
functionsDropped = true;
|
|
176
|
+
response = await send(true);
|
|
177
|
+
}
|
|
87
178
|
if (!response.ok) {
|
|
88
179
|
const retryAfterMs = readRetryAfter(response);
|
|
89
180
|
return { status: response.status, ...(retryAfterMs === null ? {} : { retryAfterMs }) };
|
|
90
181
|
}
|
|
91
182
|
const answer = await response.json();
|
|
92
183
|
const candidate = (answer && answer.candidates && answer.candidates[0]) || {};
|
|
184
|
+
const grounding = search ? { grounding: { ...readGeminiGrounding(candidate), functionsDropped } } : {};
|
|
93
185
|
const parts = (candidate.content && candidate.content.parts) || [];
|
|
94
|
-
const toolCalls = parts.filter((part) => part.functionCall).map((part, index) => ({
|
|
186
|
+
const toolCalls = functionsDropped ? [] : parts.filter((part) => part.functionCall).map((part, index) => ({
|
|
95
187
|
id: part.functionCall.id || `call_${index}`,
|
|
96
188
|
name: part.functionCall.name,
|
|
97
189
|
args: argsOf(part.functionCall.args)
|
|
98
190
|
}));
|
|
99
|
-
if (toolCalls.length) return { status: response.status, text: null, toolCalls };
|
|
100
|
-
const text = withoutThinking(parts.filter((part) => !part.thought).map((part) => part.text || '').join(''));
|
|
101
|
-
const written = readWrittenAnswer(text,
|
|
102
|
-
if (written) return { status: response.status, ...written };
|
|
103
|
-
return { status: response.status, text, cut: candidate.finishReason === 'MAX_TOKENS' };
|
|
191
|
+
if (toolCalls.length) return { status: response.status, text: null, toolCalls, ...grounding };
|
|
192
|
+
const text = withoutThinking(parts.filter((part) => !part.thought && !part.functionCall).map((part) => part.text || '').join(''));
|
|
193
|
+
const written = readWrittenAnswer(text, hasFunctions && !functionsDropped);
|
|
194
|
+
if (written) return { status: response.status, ...written, ...grounding };
|
|
195
|
+
return { status: response.status, text, cut: candidate.finishReason === 'MAX_TOKENS', ...grounding };
|
|
104
196
|
}
|
|
105
197
|
|
|
106
198
|
/**
|
|
@@ -155,4 +247,4 @@ function createGeminiProvider(options = {}) {
|
|
|
155
247
|
};
|
|
156
248
|
}
|
|
157
249
|
|
|
158
|
-
module.exports = { askGeminiModel, createGeminiProvider };
|
|
250
|
+
module.exports = { askGeminiModel, createGeminiProvider, readGeminiGrounding };
|