@astratra/ai 1.4.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 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, et une petite boucle d'orchestration
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
@@ -201,10 +325,12 @@ const lignes = buildPassagesContext({
201
325
 
202
326
  ## Le texte de la réponse
203
327
 
204
- `tidyMarkdown` ramène la réponse au Markdown qu'un téléphone dessine,
205
- `plainText` l'enlève pour une voix, et `verifyQuotations(texte, { findReferences,
206
- resolve })` remplace une citation infidèle suivie de sa référence par le vrai
207
- texte — ce qu'est une référence et où vit son texte t'appartient.
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.
208
334
 
209
335
  ## La langue de la réponse, la cadence, les points compatibles OpenAI
210
336
 
@@ -213,7 +339,8 @@ texte — ce qu'est une référence et où vit son texte t'appartient.
213
339
  seulement au-dessus d'un seuil — bien plus haut pour deux mots.
214
340
  - `createAskLimit({ max, windowMs, code })` : fenêtre glissante par personne ;
215
341
  le refus porte un code et l'attente, jamais une phrase ; les comptes qui
216
- n'écrivent plus sont oubliés.
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).
217
344
  - `createOpenAICompatibleProvider({ id, url, getKey, models, fetch })` : un
218
345
  fournisseur pour le routeur. La clé est relue à chaque appel, une erreur porte
219
346
  le statut HTTP (429 → refroidissement) et jamais la clé, des arguments d'outil
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.4.0",
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"
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
  }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Le travail d'un agent envoyé à l'app au fil de l'eau (server-sent events) :
3
+ * un bloc par évènement, "event: <type>\ndata: <json>\n\n".
4
+ *
5
+ * Quand la personne part avant la fin, `signal` s'interrompt pour que le
6
+ * travail s'arrête aussi ; un flux fermé par le serveur n'est pas un départ.
7
+ * Écrire après la fin ne fait rien : le travail qui finissait ne plante pas.
8
+ */
9
+
10
+ const HEADERS = {
11
+ 'Content-Type': 'text/event-stream; charset=utf-8',
12
+ 'Cache-Control': 'no-cache, no-transform',
13
+ Connection: 'keep-alive',
14
+ /* Un proxy devant (nginx) retiendrait sinon les évènements jusqu'à la fin. */
15
+ 'X-Accel-Buffering': 'no'
16
+ };
17
+
18
+ /**
19
+ * @param {import('http').ServerResponse} res une réponse Node (Express compris).
20
+ * @param {object} [options]
21
+ * @param {Record<string, string>} [options.headers] ajoutés à ceux du flux.
22
+ * @returns {{ send: (type: string, data: unknown) => void, close: () => void, signal: AbortSignal }}
23
+ */
24
+ function openEventStream(res, options = {}) {
25
+ if (!res || typeof res.write !== 'function' || typeof res.setHeader !== 'function') {
26
+ throw new Error('openEventStream requires a Node.js ServerResponse.');
27
+ }
28
+ const left = new globalThis.AbortController();
29
+ res.statusCode = 200;
30
+ for (const [name, value] of Object.entries({ ...HEADERS, ...(options.headers || {}) })) res.setHeader(name, value);
31
+ res.flushHeaders();
32
+ res.on('close', () => {
33
+ if (!res.writableEnded) left.abort();
34
+ });
35
+ const open = () => !res.writableEnded && !left.signal.aborted;
36
+ return {
37
+ signal: left.signal,
38
+ send(type, data) {
39
+ if (open()) res.write(`event: ${type}\ndata: ${JSON.stringify(data)}\n\n`);
40
+ },
41
+ close() {
42
+ if (open()) res.end();
43
+ }
44
+ };
45
+ }
46
+
47
+ module.exports = { openEventStream, EVENT_STREAM_HEADERS: HEADERS };
package/src/gemini.js ADDED
@@ -0,0 +1,152 @@
1
+ /**
2
+ * L'API Gemini de Google (generateContent) : la même requête que le format
3
+ * OpenAI (consigne, transcription, outils, photos), traduite dans la sienne,
4
+ * et sa réponse lue de la même façon.
5
+ *
6
+ * Ce que l'usage a appris :
7
+ *
8
+ * - Gemma ne prend pas de consigne système : elle passe en tête du premier
9
+ * message, les photos restant après ;
10
+ * - un modèle qui réfléchit rend sa réflexion en parties à elle (`thought`) :
11
+ * seule la réponse est gardée ;
12
+ * - une réponse arrêtée à sa longueur (MAX_TOKENS) le dit (`cut`), pour que le
13
+ * routeur la garde en dernier recours seulement ;
14
+ * - la clé part dans l'en-tête, jamais dans l'adresse (où elle finirait dans
15
+ * les journaux).
16
+ */
17
+
18
+ const { providerResult, readWrittenAnswer, withoutThinking } = require('./modelAnswers');
19
+
20
+ const DEFAULT_ENDPOINT = 'https://generativelanguage.googleapis.com/v1beta/models';
21
+ const DEFAULT_TIMEOUT_MS = 45_000;
22
+ const noSystemInstructionByDefault = (model) => String(model).startsWith('gemma-');
23
+
24
+ /* Des arguments illisibles (null) repartent en objet vide : Gemini refuse autre chose. */
25
+ const argsOf = (args) => (args && typeof args === 'object' && !Array.isArray(args) ? args : {});
26
+
27
+ function contentsOf(messages) {
28
+ return (Array.isArray(messages) ? messages : []).map((message) => {
29
+ if (message.role === 'assistant') {
30
+ const parts = [];
31
+ const text = message.text === undefined ? message.content : message.text;
32
+ if (text) parts.push({ text });
33
+ for (const call of message.toolCalls || []) parts.push({ functionCall: { name: call.name, args: argsOf(call.args) } });
34
+ return { role: 'model', parts };
35
+ }
36
+ if (message.role === 'tool') {
37
+ return { role: 'user', parts: [{ functionResponse: { name: message.name, response: { result: message.result } } }] };
38
+ }
39
+ /* Une photo jointe suit les mots, en ligne. */
40
+ const text = message.text === undefined ? message.content || '' : message.text;
41
+ return { role: 'user', parts: [{ text }, ...(message.images || []).map(({ mimeType, data }) => ({ inlineData: { mimeType, data } }))] };
42
+ });
43
+ }
44
+
45
+ /** Le corps de la requête pour un modèle. */
46
+ function requestBody(model, request, noSystemInstruction) {
47
+ const contents = contentsOf(request.messages);
48
+ const generationConfig = {
49
+ temperature: request.temperature === undefined ? 0.4 : request.temperature,
50
+ maxOutputTokens: request.maxTokens || 1200
51
+ };
52
+ const functions = request.tools && request.tools.length ? { tools: [{ functionDeclarations: request.tools }] } : {};
53
+ const system = request.system || '';
54
+ if (!noSystemInstruction(model)) {
55
+ return { ...(system ? { systemInstruction: { parts: [{ text: system }] } } : {}), contents, generationConfig, ...functions };
56
+ }
57
+ if (!system) return { contents, generationConfig, ...functions };
58
+ const [first, ...rest] = contents;
59
+ const firstParts = first ? first.parts : [];
60
+ const head = firstParts[0] && typeof firstParts[0].text === 'string' ? firstParts[0].text : '';
61
+ return {
62
+ contents: [{ ...(first || { role: 'user' }), parts: [{ text: `${system}\n\n${head}` }, ...firstParts.slice(1)] }, ...rest],
63
+ generationConfig,
64
+ ...functions
65
+ };
66
+ }
67
+
68
+ /**
69
+ * Demande à un modèle Gemini.
70
+ * @param {string} model
71
+ * @param {{ system?: string, messages: object[], tools?: object[], maxTokens?: number, temperature?: number }} request
72
+ * @param {{ key: string, fetch: Function, signal?: AbortSignal, timeoutMs?: number, endpoint?: string, noSystemInstruction?: Function }} io
73
+ * @returns {Promise<{ status: number, text?: string|null, toolCalls?: object[], cut?: boolean }>}
74
+ * Un refus se résout en `{ status }` — rien n'est levé pour lui.
75
+ */
76
+ async function askGeminiModel(model, request, io = {}) {
77
+ if (typeof io.fetch !== 'function') throw new Error('askGeminiModel requires io.fetch.');
78
+ const timeout = globalThis.AbortSignal.timeout(io.timeoutMs || DEFAULT_TIMEOUT_MS);
79
+ const signal = io.signal ? globalThis.AbortSignal.any([io.signal, timeout]) : timeout;
80
+ const response = await io.fetch(`${io.endpoint || DEFAULT_ENDPOINT}/${model}:generateContent`, {
81
+ method: 'POST',
82
+ headers: { 'content-type': 'application/json', 'x-goog-api-key': io.key },
83
+ body: JSON.stringify(requestBody(model, request, io.noSystemInstruction || noSystemInstructionByDefault)),
84
+ signal
85
+ });
86
+ if (!response.ok) return { status: response.status };
87
+ const answer = await response.json();
88
+ const candidate = (answer && answer.candidates && answer.candidates[0]) || {};
89
+ const parts = (candidate.content && candidate.content.parts) || [];
90
+ const toolCalls = parts.filter((part) => part.functionCall).map((part, index) => ({
91
+ id: part.functionCall.id || `call_${index}`,
92
+ name: part.functionCall.name,
93
+ args: argsOf(part.functionCall.args)
94
+ }));
95
+ if (toolCalls.length) return { status: response.status, text: null, toolCalls };
96
+ const text = withoutThinking(parts.filter((part) => !part.thought).map((part) => part.text || '').join(''));
97
+ const written = readWrittenAnswer(text, Boolean(request.tools && request.tools.length));
98
+ if (written) return { status: response.status, ...written };
99
+ return { status: response.status, text, cut: candidate.finishReason === 'MAX_TOKENS' };
100
+ }
101
+
102
+ /**
103
+ * Un fournisseur Gemini pour createProviderRouter : mêmes options que
104
+ * createOpenAICompatibleProvider, sans adresse (le point d'accès de Google,
105
+ * ou `endpoint`).
106
+ *
107
+ * @param {object} options
108
+ * @param {string} [options.id='gemini']
109
+ * @param {Function} options.getKey (ctx) => clé, relue à chaque appel.
110
+ * @param {object[]} options.models
111
+ * @param {Function} options.fetch `ctx.fetch` le remplace pour un appel.
112
+ * @param {Function} [options.lane] (ctx) => voie | null : une clé à elle pour cet usage.
113
+ * @param {boolean} [options.detailed]
114
+ * @param {number} [options.timeoutMs] `ctx.timeoutMs` le remplace pour un appel.
115
+ * @param {string} [options.endpoint]
116
+ * @param {Function} [options.noSystemInstruction] (modelId) => true pour un modèle sans consigne système. Défaut : Gemma.
117
+ * @param {Function} [options.toRequest] (prompt, ctx) => { system?, messages, tools?, maxTokens? }.
118
+ */
119
+ function createGeminiProvider(options = {}) {
120
+ if (typeof options.getKey !== 'function') throw new Error('createGeminiProvider requires options.getKey.');
121
+ if (typeof options.fetch !== 'function') throw new Error('createGeminiProvider requires options.fetch.');
122
+ const id = options.id || 'gemini';
123
+ const toRequest = options.toRequest || ((prompt) => ({ messages: [{ role: 'user', text: String(prompt) }] }));
124
+
125
+ return {
126
+ id,
127
+ models: options.models || [],
128
+ ...(typeof options.lane === 'function' ? { lane: options.lane } : {}),
129
+ async available(ctx = {}) {
130
+ return Boolean(await options.getKey(ctx));
131
+ },
132
+ async call(prompt, ctx = {}, model = {}) {
133
+ const key = await options.getKey(ctx);
134
+ if (!key) {
135
+ const missing = new Error(`Provider "${id}" has no key.`);
136
+ missing.statusCode = 401;
137
+ throw missing;
138
+ }
139
+ const answer = await askGeminiModel(model.id, { maxTokens: model.maxTokens, ...toRequest(prompt, ctx) }, {
140
+ key,
141
+ fetch: typeof ctx.fetch === 'function' ? ctx.fetch : options.fetch,
142
+ signal: ctx.signal,
143
+ timeoutMs: ctx.timeoutMs || options.timeoutMs,
144
+ endpoint: options.endpoint,
145
+ noSystemInstruction: options.noSystemInstruction
146
+ });
147
+ return providerResult(id, answer, options.detailed);
148
+ }
149
+ };
150
+ }
151
+
152
+ module.exports = { askGeminiModel, createGeminiProvider };