@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Astratra
3
+ Copyright (c) 2026 Astratra contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
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 Oracle et Tertius. Ce
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 (Oracle and Tertius)
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 Oracle's word/keyword rules (with
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 Oracle's Groq → Mistral → Gemini → Vercel → Ollama and
693
- Tertius's distinct quick/chat/pilot orders are both expressible.
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 Scolaris model server and its Bearer file |
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 (Scolaris HTTP protocol)
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. Tertius's generic in-process embedding
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
@@ -0,0 +1,4 @@
1
+ {
2
+ "main": "../src/guards/index.js",
3
+ "types": "../src/guards/index.d.ts"
4
+ }
@@ -0,0 +1,4 @@
1
+ {
2
+ "main": "../../src/guards/testing/index.js",
3
+ "types": "../../src/guards/testing/index.d.ts"
4
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.7.0",
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 functions = request.tools && request.tools.length ? { tools: [{ functionDeclarations: request.tools }] } : {};
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 response = await io.fetch(`${io.endpoint || DEFAULT_ENDPOINT}/${model}:generateContent`, {
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, Boolean(request.tools && request.tools.length));
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 };