@astratra/ai 1.3.0 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +262 -2
- package/package.json +2 -1
- package/src/agentLoop.js +88 -11
- package/src/answerText.js +137 -0
- package/src/askLimit.js +73 -0
- package/src/breakers.js +97 -0
- package/src/eventStream.js +47 -0
- package/src/gemini.js +152 -0
- package/src/index.d.ts +452 -3
- package/src/index.js +13 -1
- package/src/language.js +85 -0
- package/src/masking.js +279 -0
- package/src/modelAnswers.js +119 -0
- package/src/nativeTools.js +256 -0
- package/src/openaiCompatible.js +158 -0
- package/src/passages.js +101 -0
- package/src/providerRouter.js +224 -44
- package/src/sources.js +243 -0
- package/src/webSearch.js +71 -0
package/src/breakers.js
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One circuit per provider — never one for all.
|
|
3
|
+
*
|
|
4
|
+
* A single breaker shared by every outside dependency looks tidy and is a
|
|
5
|
+
* trap: a slow reranker opened it, and the name detector behind the privacy
|
|
6
|
+
* mask went dark with it for a full minute. The failing thing must be the only
|
|
7
|
+
* thing that stops.
|
|
8
|
+
*
|
|
9
|
+
* This package ships no breaker of its own. `@astratra/resilience` has one,
|
|
10
|
+
* with a single half-open probe; inject its factory:
|
|
11
|
+
*
|
|
12
|
+
* const { createCircuitBreaker } = require('@astratra/resilience');
|
|
13
|
+
* const breakers = createBreakerPool({
|
|
14
|
+
* create: (id) => createCircuitBreaker({ name: id, isFailure: isProviderOutage })
|
|
15
|
+
* });
|
|
16
|
+
*
|
|
17
|
+
* Any object with `call(fn)` fits; `status()` and `reset()` are used when
|
|
18
|
+
* present.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Is this error the provider being DOWN, rather than refusing this request?
|
|
23
|
+
*
|
|
24
|
+
* A 429 is the provider saying "slow down" — the router's cooldown handles it.
|
|
25
|
+
* A 400, 401, 403 or 404 is about the request or the key: opening the circuit
|
|
26
|
+
* on it would take a healthy provider away from every other request. Timeouts,
|
|
27
|
+
* network failures and 5xx are outages.
|
|
28
|
+
*/
|
|
29
|
+
function isProviderOutage(error) {
|
|
30
|
+
if (!error) return false;
|
|
31
|
+
const status = [error.statusCode, error.status, Number(error.code)].find((value) => Number.isInteger(value) && value >= 100 && value < 600);
|
|
32
|
+
if (status === undefined) return true;
|
|
33
|
+
if (status === 408) return true;
|
|
34
|
+
return status >= 500;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* @param {object} options
|
|
39
|
+
* @param {Function} options.create (key) => breaker. Called once per key.
|
|
40
|
+
*/
|
|
41
|
+
function createBreakerPool(options = {}) {
|
|
42
|
+
const create = options.create;
|
|
43
|
+
if (typeof create !== 'function') {
|
|
44
|
+
throw new Error('createBreakerPool requires options.create: (key) => breaker.');
|
|
45
|
+
}
|
|
46
|
+
const pool = new Map();
|
|
47
|
+
const owners = new Map();
|
|
48
|
+
|
|
49
|
+
function get(key) {
|
|
50
|
+
const name = String(key);
|
|
51
|
+
if (pool.has(name)) return pool.get(name);
|
|
52
|
+
const breaker = create(name);
|
|
53
|
+
if (!breaker || typeof breaker.call !== 'function') {
|
|
54
|
+
throw new Error(`createBreakerPool: create("${name}") must return an object with call(fn).`);
|
|
55
|
+
}
|
|
56
|
+
/* The mistake this module exists to prevent: a factory that hands back the
|
|
57
|
+
same breaker for every key re-creates the shared circuit. */
|
|
58
|
+
if (owners.has(breaker)) {
|
|
59
|
+
throw new Error(`createBreakerPool: "${name}" received the breaker of "${owners.get(breaker)}" — one breaker per key.`);
|
|
60
|
+
}
|
|
61
|
+
owners.set(breaker, name);
|
|
62
|
+
pool.set(name, breaker);
|
|
63
|
+
return breaker;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Run `fn` under the breaker of `key`. */
|
|
67
|
+
const run = (key, fn) => get(key).call(fn);
|
|
68
|
+
|
|
69
|
+
function status() {
|
|
70
|
+
const out = {};
|
|
71
|
+
for (const [name, breaker] of pool) {
|
|
72
|
+
out[name] = typeof breaker.status === 'function' ? breaker.status() : { name };
|
|
73
|
+
}
|
|
74
|
+
return out;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function stateOf(key) {
|
|
78
|
+
const breaker = pool.get(String(key));
|
|
79
|
+
if (!breaker || typeof breaker.status !== 'function') return null;
|
|
80
|
+
const current = breaker.status();
|
|
81
|
+
return current && current.state ? current.state : null;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function reset(key) {
|
|
85
|
+
const targets = key === undefined ? [...pool.values()] : [pool.get(String(key))].filter(Boolean);
|
|
86
|
+
for (const breaker of targets) if (typeof breaker.reset === 'function') breaker.reset();
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
return { get, run, status, stateOf, reset, keys: () => [...pool.keys()] };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** An error thrown by a breaker that refused to call — not a provider failure. */
|
|
93
|
+
function isCircuitOpen(error) {
|
|
94
|
+
return Boolean(error && (error.code === 'CIRCUIT_OPEN' || error.name === 'CircuitOpenError'));
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
module.exports = { createBreakerPool, isProviderOutage, isCircuitOpen };
|
|
@@ -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 };
|