@astratra/ai 1.4.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +243 -7
- package/deploy/llama-cpp/.env.example +10 -0
- package/deploy/llama-cpp/docker-compose.yml +47 -0
- package/package.json +7 -4
- package/src/agentLoop.js +101 -5
- package/src/answerText.js +21 -1
- package/src/askLimit.js +5 -1
- package/src/eventStream.js +47 -0
- package/src/gemini.js +152 -0
- package/src/index.d.ts +293 -13
- package/src/index.js +6 -1
- package/src/llamaCpp.js +192 -0
- package/src/modelAnswers.js +119 -0
- package/src/nativeTools.js +256 -0
- package/src/openaiCompatible.js +33 -45
- package/src/providerRouter.js +154 -40
- package/src/toolRegistry.js +13 -2
- package/src/webSearch.js +71 -0
|
@@ -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 };
|
package/src/index.d.ts
CHANGED
|
@@ -14,15 +14,34 @@ export interface Provider {
|
|
|
14
14
|
models: ProviderModel[];
|
|
15
15
|
/** False for a model running on this machine: the router does not mask for it. */
|
|
16
16
|
external?: boolean;
|
|
17
|
-
|
|
17
|
+
/** Faux (sans clé, éteint) : le routeur le saute sans rien lui demander ni compter d'échec. */
|
|
18
|
+
available?(ctx: Record<string, unknown>): Awaitable<boolean>;
|
|
19
|
+
/** Une voie : une clé à elle pour cet usage, qui se repose seule ("fournisseur:modèle@voie"). */
|
|
20
|
+
lane?(ctx: Record<string, unknown>): string | null | undefined;
|
|
21
|
+
call(prompt: any, ctx: Record<string, unknown>, model: ProviderModel): Awaitable<unknown>;
|
|
18
22
|
[key: string]: unknown;
|
|
19
23
|
}
|
|
20
24
|
|
|
25
|
+
/** Un candidat de `request.candidates` : un modèle d'un fournisseur, avec ses champs (extra, vision…). */
|
|
26
|
+
export interface RouteCandidate {
|
|
27
|
+
provider: string;
|
|
28
|
+
model: string;
|
|
29
|
+
[field: string]: unknown;
|
|
30
|
+
}
|
|
31
|
+
|
|
21
32
|
export interface ProviderRequest {
|
|
22
33
|
complexity?: string;
|
|
23
34
|
estimatedTokens?: number;
|
|
24
35
|
intent?: string;
|
|
25
36
|
maxTokens?: number;
|
|
37
|
+
/** L'ordre de CETTE demande, à travers les fournisseurs. */
|
|
38
|
+
candidates?: RouteCandidate[];
|
|
39
|
+
/** Ne garde que les modèles aptes à cette demande (une photo : ceux qui voient). */
|
|
40
|
+
select?: (model: ProviderModel, provider: Provider) => boolean;
|
|
41
|
+
/** Faux : la réponse est refusée, le modèle suivant est demandé (ce n'est pas une panne du modèle). */
|
|
42
|
+
accepts?: (value: any) => boolean;
|
|
43
|
+
/** Vrai : réponse coupée, gardée en dernier recours seulement. */
|
|
44
|
+
partial?: (value: any) => boolean;
|
|
26
45
|
[key: string]: unknown;
|
|
27
46
|
}
|
|
28
47
|
|
|
@@ -37,8 +56,32 @@ export interface ProviderRouterConfig {
|
|
|
37
56
|
redisUrl?: string;
|
|
38
57
|
/** One circuit per provider: a factory (providerId) => breaker, or a pool. */
|
|
39
58
|
breakers?: ((providerId: string) => BreakerLike) | BreakerPool;
|
|
59
|
+
/** Ce qui met un modèle au repos (cooldownMs). Défaut : un 429. */
|
|
60
|
+
cooldownOn?: (error: any) => boolean;
|
|
61
|
+
/** 'try' : quand tous les candidats se reposent, on les essaie quand même. Défaut 'skip'. */
|
|
62
|
+
whenAllCooling?: 'skip' | 'try';
|
|
63
|
+
/** L'horloge des repos et des quotas. Défaut Date.now. */
|
|
64
|
+
now?: () => number;
|
|
40
65
|
}
|
|
41
66
|
|
|
67
|
+
export interface RouteResult<T = unknown> {
|
|
68
|
+
value: T;
|
|
69
|
+
provider: string;
|
|
70
|
+
model: string;
|
|
71
|
+
/** "fournisseur:modèle", suivi de "@voie" quand le fournisseur en a une pour cet appel. */
|
|
72
|
+
key: string;
|
|
73
|
+
/** La réponse coupée gardée en dernier recours. */
|
|
74
|
+
partial: boolean;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Levée par ask/route (AppError 503) : `code` vaut 'AI_NO_PROVIDER' (aucun
|
|
79
|
+
* fournisseur disponible), 'AI_NO_MATCH' (aucun ne convient à la demande) ou
|
|
80
|
+
* 'AI_UNAVAILABLE' (tous essayés, aucun n'a répondu ; `errors` les porte).
|
|
81
|
+
* Une demande abandonnée (ctx.signal) lève la raison de l'appelant.
|
|
82
|
+
*/
|
|
83
|
+
export type RouterErrorCode = 'AI_NO_PROVIDER' | 'AI_NO_MATCH' | 'AI_UNAVAILABLE';
|
|
84
|
+
|
|
42
85
|
export interface ProviderStats {
|
|
43
86
|
provider: string;
|
|
44
87
|
rpm_now: number;
|
|
@@ -55,9 +98,13 @@ export interface ProviderStats {
|
|
|
55
98
|
}
|
|
56
99
|
|
|
57
100
|
export interface ProviderRouter {
|
|
58
|
-
ask(prompt:
|
|
59
|
-
/**
|
|
101
|
+
ask(prompt: any, request?: ProviderRequest, ctx?: Record<string, unknown>): Promise<unknown>;
|
|
102
|
+
/** Comme ask, et dit qui a répondu. */
|
|
103
|
+
route(prompt: any, request?: ProviderRequest, ctx?: Record<string, unknown>): Promise<RouteResult>;
|
|
104
|
+
/** Les entrées sont indexées par "providerId:modelId" (et "@voie"). */
|
|
60
105
|
getStats(): Record<string, ProviderStats>;
|
|
106
|
+
/** Oublie repos, dégradations, échecs et usage. */
|
|
107
|
+
reset(): void;
|
|
61
108
|
stop(): void;
|
|
62
109
|
breakers: BreakerPool | null;
|
|
63
110
|
}
|
|
@@ -71,12 +118,19 @@ export interface ToolDefinition<TParams = Record<string, unknown>, TResult = unk
|
|
|
71
118
|
roles: string[];
|
|
72
119
|
/** Reaches outside (web search, third-party API): its parameters are masked. */
|
|
73
120
|
external?: boolean;
|
|
121
|
+
/** Niveau de risque déclaré ; absent, le registre utilise UNKNOWN. */
|
|
122
|
+
risk?: DeclaredToolRisk;
|
|
74
123
|
params?: Record<string, unknown>;
|
|
75
124
|
handler(params: TParams, ctx: Record<string, unknown>): Awaitable<TResult>;
|
|
76
125
|
}
|
|
77
126
|
|
|
78
|
-
export
|
|
127
|
+
export type ToolRisk = 'LOW' | 'MEDIUM' | 'HIGH' | 'UNKNOWN';
|
|
128
|
+
export type DeclaredToolRisk = Exclude<ToolRisk, 'UNKNOWN'>;
|
|
129
|
+
export const TOOL_RISKS: Readonly<Record<ToolRisk, number>>;
|
|
130
|
+
|
|
131
|
+
export interface RegisteredTool<TParams = Record<string, unknown>, TResult = unknown> extends Omit<ToolDefinition<TParams, TResult>, 'risk'> {
|
|
79
132
|
params: Record<string, unknown>;
|
|
133
|
+
risk: ToolRisk;
|
|
80
134
|
}
|
|
81
135
|
|
|
82
136
|
export interface ToolRegistry {
|
|
@@ -136,9 +190,28 @@ export interface AgentLoopOptions {
|
|
|
136
190
|
maxMs?: number;
|
|
137
191
|
/** When steps or time run out: one last turn without tools, with this instruction. */
|
|
138
192
|
finalInstruction?: string;
|
|
193
|
+
/** Seuils d'appels strictement identiques (défauts : 3, 5 et 8). */
|
|
194
|
+
loopGuard?: { reminder?: number; firmReminder?: number; stop?: number };
|
|
195
|
+
/** Mise de côté au-delà du seuil en caractères (défaut : 12 000). */
|
|
196
|
+
spill?: { threshold?: number; store?: SpillStore };
|
|
197
|
+
/** Politique active uniquement lorsqu'elle est fournie : always, never ou seuil de risque. */
|
|
198
|
+
confirmationPolicy?: 'always' | 'never' | { threshold: ToolRisk };
|
|
199
|
+
/** Analyseurs supplémentaires ; le risque le plus élevé prévaut. */
|
|
200
|
+
riskAnalyzers?: Array<(toolCall: ToolCall, ctx: Record<string, unknown>, tool: RegisteredTool) => Awaitable<ToolRisk>>;
|
|
201
|
+
/** Adaptateur de createPendingActions ; les actions créées attendent leur approbation. */
|
|
202
|
+
pendingActions?: Pick<PendingActions, 'propose'>;
|
|
203
|
+
onEvent?: (event: { type: 'tool_loop_warning' | 'tool_loop_stopped'; name: string; repetitions: number; message?: string; reason?: string }) => void;
|
|
139
204
|
now?: () => number;
|
|
140
205
|
}
|
|
141
206
|
|
|
207
|
+
export interface SpillStore {
|
|
208
|
+
set(id: string, value: string): Awaitable<void>;
|
|
209
|
+
get(id: string): Awaitable<string | undefined>;
|
|
210
|
+
}
|
|
211
|
+
export function createMemorySpillStore(): SpillStore;
|
|
212
|
+
export const DEFAULT_LOOP_THRESHOLDS: Readonly<{ reminder: number; firmReminder: number; stop: number }>;
|
|
213
|
+
export const DEFAULT_SPILL_THRESHOLD: number;
|
|
214
|
+
|
|
142
215
|
export function runAgentLoop(options: AgentLoopOptions): Promise<string>;
|
|
143
216
|
|
|
144
217
|
export type ActionStatus = 'proposed' | 'approved' | 'rejected' | 'executing' | 'executed' | 'failed';
|
|
@@ -455,7 +528,10 @@ export function rerankResults<R, S, F extends { results: R[]; sources?: S[] }>(
|
|
|
455
528
|
/* ─────────────────── Answer text ─────────────────── */
|
|
456
529
|
|
|
457
530
|
export function plainText(text: unknown): string;
|
|
458
|
-
|
|
531
|
+
/** `remove` : des expressions globales retirées après les marques (ce que l'app ne montre jamais). */
|
|
532
|
+
export function tidyMarkdown(text: unknown, options?: { removeEmoji?: boolean; remove?: RegExp[] }): string;
|
|
533
|
+
/** Un texte coupé ramené à sa dernière phrase entière. */
|
|
534
|
+
export function wholeSentences(text: unknown, options?: { marks?: string[] }): string;
|
|
459
535
|
export function isFaithfulQuotation(quoted: string, source: string): boolean;
|
|
460
536
|
export function verifyQuotations<Refs = unknown>(text: string, options: {
|
|
461
537
|
findReferences: (text: string) => Awaitable<Array<{ start: number; end: number; refs: Refs }>>;
|
|
@@ -514,6 +590,10 @@ export interface ChatToolCall {
|
|
|
514
590
|
args: Record<string, unknown> | null;
|
|
515
591
|
/** The model sent arguments that are not a JSON object. */
|
|
516
592
|
invalid?: true;
|
|
593
|
+
/** Pourquoi : 'not_json' (illisible) ou 'not_object'. */
|
|
594
|
+
invalidReason?: 'not_json' | 'not_object';
|
|
595
|
+
/** L'erreur de lecture, pour 'not_json'. */
|
|
596
|
+
invalidDetail?: string;
|
|
517
597
|
}
|
|
518
598
|
|
|
519
599
|
export type FetchLike = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; json(): Promise<any> }>;
|
|
@@ -524,16 +604,216 @@ export function askChatModel(
|
|
|
524
604
|
io: { fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number }
|
|
525
605
|
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
|
|
526
606
|
|
|
527
|
-
export function readToolArguments(raw: unknown): { args: Record<string, unknown> | null; invalid: boolean };
|
|
607
|
+
export function readToolArguments(raw: unknown): { args: Record<string, unknown> | null; invalid: boolean; reason?: 'not_json' | 'not_object'; detail?: string };
|
|
528
608
|
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
609
|
+
/** Les appels d'outil écrits dans un texte (<function=…>, <tool_call>{…}</tool_call>), relus. */
|
|
610
|
+
export function readWrittenToolCalls(text: string): Array<{ id: string; name: string; args: Record<string, unknown> }>;
|
|
611
|
+
/** Le raisonnement entre balises think retiré, même ouvert sans fin ou fermé sans ouverture. */
|
|
612
|
+
export function withoutThinking(content: unknown): string;
|
|
613
|
+
|
|
614
|
+
export interface ChatRequest {
|
|
615
|
+
system?: string;
|
|
616
|
+
messages: ChatMessage[];
|
|
617
|
+
tools?: Array<Record<string, unknown>>;
|
|
618
|
+
maxTokens?: number;
|
|
619
|
+
temperature?: number;
|
|
620
|
+
}
|
|
621
|
+
|
|
622
|
+
/** Ce qu'un fournisseur `detailed` rend au routeur. */
|
|
623
|
+
export interface DetailedAnswer {
|
|
624
|
+
text: string | null;
|
|
625
|
+
toolCalls: ChatToolCall[];
|
|
626
|
+
cut: boolean;
|
|
627
|
+
}
|
|
628
|
+
|
|
629
|
+
export interface ChatProviderOptions {
|
|
630
|
+
getKey: (ctx: Record<string, unknown>) => Awaitable<string | null | undefined>;
|
|
631
|
+
models?: ProviderModel[];
|
|
632
|
+
/** `ctx.fetch` le remplace pour un appel. */
|
|
534
633
|
fetch: FetchLike;
|
|
535
|
-
external?: boolean;
|
|
536
634
|
timeoutMs?: number;
|
|
635
|
+
lane?: (ctx: Record<string, unknown>) => string | null | undefined;
|
|
636
|
+
/** Vrai : l'appel rend { text, toolCalls, cut } au lieu du texte seul. */
|
|
637
|
+
detailed?: boolean;
|
|
638
|
+
toRequest?: (prompt: any, ctx: Record<string, unknown>) => ChatRequest;
|
|
639
|
+
}
|
|
640
|
+
|
|
641
|
+
export function createOpenAICompatibleProvider(options: ChatProviderOptions & {
|
|
642
|
+
id: string;
|
|
643
|
+
url: string | ((ctx: Record<string, unknown>) => string | null | undefined);
|
|
644
|
+
external?: boolean;
|
|
537
645
|
extra?: Record<string, unknown>;
|
|
538
|
-
toRequest?: (prompt: string, ctx: Record<string, unknown>) => { system?: string; messages: ChatMessage[] };
|
|
539
646
|
}): Provider;
|
|
647
|
+
|
|
648
|
+
/* ─────────────────── Gemini ─────────────────── */
|
|
649
|
+
|
|
650
|
+
export function askGeminiModel(
|
|
651
|
+
model: string,
|
|
652
|
+
request: ChatRequest,
|
|
653
|
+
io: { key: string; fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number; endpoint?: string; noSystemInstruction?: (model: string) => boolean }
|
|
654
|
+
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
|
|
655
|
+
|
|
656
|
+
export function createGeminiProvider(options: ChatProviderOptions & {
|
|
657
|
+
id?: string;
|
|
658
|
+
endpoint?: string;
|
|
659
|
+
/** Défaut : les modèles Gemma, qui ne prennent pas de consigne système. */
|
|
660
|
+
noSystemInstruction?: (model: string) => boolean;
|
|
661
|
+
}): Provider;
|
|
662
|
+
|
|
663
|
+
/* ─────────────────── Outils natifs et leur boucle ─────────────────── */
|
|
664
|
+
|
|
665
|
+
export type NativeToolKind = 'read' | 'write' | 'confirm' | string;
|
|
666
|
+
|
|
667
|
+
export interface NativeToolResult {
|
|
668
|
+
data?: unknown;
|
|
669
|
+
sources?: Array<Record<string, unknown>>;
|
|
670
|
+
card?: Record<string, unknown>;
|
|
671
|
+
undo?: unknown;
|
|
672
|
+
[key: string]: unknown;
|
|
673
|
+
}
|
|
674
|
+
|
|
675
|
+
export interface NativeTool<Ctx = Record<string, unknown>> {
|
|
676
|
+
name: string;
|
|
677
|
+
description: string;
|
|
678
|
+
parameters: { type: 'object'; [key: string]: unknown };
|
|
679
|
+
kind: NativeToolKind;
|
|
680
|
+
summary?: (args: Record<string, unknown>) => Record<string, string | number>;
|
|
681
|
+
run(args: Record<string, unknown>, ctx: Ctx & { signal: AbortSignal }): Awaitable<NativeToolResult | null | undefined>;
|
|
682
|
+
perform?(args: Record<string, unknown>, ctx: Ctx): Awaitable<NativeToolResult | null | undefined>;
|
|
683
|
+
undo?(undo: unknown, ctx: Ctx): Awaitable<unknown>;
|
|
684
|
+
}
|
|
685
|
+
|
|
686
|
+
export const NATIVE_TOOL_KINDS: string[];
|
|
687
|
+
export function validateNativeTools<T extends NativeTool<any>>(tools: T[], options?: { kinds?: string[]; requireSummary?: boolean }): T[];
|
|
688
|
+
export function toolSpecs(tools: NativeTool<any>[]): Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
|
|
689
|
+
export function stepParams(tool: NativeTool<any> | null | undefined, args: unknown, options?: { max?: number }): Record<string, string | number>;
|
|
690
|
+
|
|
691
|
+
export interface NativeToolCall {
|
|
692
|
+
id: string;
|
|
693
|
+
name: string;
|
|
694
|
+
args: Record<string, unknown> | null;
|
|
695
|
+
invalid?: boolean;
|
|
696
|
+
invalidReason?: 'not_json' | 'not_object';
|
|
697
|
+
invalidDetail?: string;
|
|
698
|
+
}
|
|
699
|
+
|
|
700
|
+
export interface ToolMessage {
|
|
701
|
+
role: 'tool';
|
|
702
|
+
toolCallId: string;
|
|
703
|
+
name: string;
|
|
704
|
+
result: unknown;
|
|
705
|
+
}
|
|
706
|
+
|
|
707
|
+
export function createToolCaller<Ctx = Record<string, unknown>>(options: {
|
|
708
|
+
tools: Map<string, NativeTool<Ctx>> | NativeTool<Ctx>[];
|
|
709
|
+
context?: Ctx;
|
|
710
|
+
signal?: AbortSignal;
|
|
711
|
+
timeoutMs?: number;
|
|
712
|
+
now?: () => number;
|
|
713
|
+
emit?: (type: 'step' | 'step_done', data: Record<string, unknown>) => void;
|
|
714
|
+
keep?: (sources: unknown, data: unknown) => void;
|
|
715
|
+
record?: (entry: { tool: NativeTool<Ctx>; args: Record<string, unknown> | null; found: NativeToolResult }) => Awaitable<void>;
|
|
716
|
+
onCall?: (stats: { name: string; ms: number; ok: boolean }) => void;
|
|
717
|
+
resultMax?: number;
|
|
718
|
+
messages?: {
|
|
719
|
+
unknownTool?: (name: string) => string;
|
|
720
|
+
timeout?: () => string;
|
|
721
|
+
invalidArguments?: (call: { name: string; invalidReason?: string; invalidDetail?: string }) => string;
|
|
722
|
+
waiting?: string;
|
|
723
|
+
};
|
|
724
|
+
}): (call: NativeToolCall) => Promise<ToolMessage>;
|
|
725
|
+
|
|
726
|
+
export interface ToolTurn {
|
|
727
|
+
text: string | null;
|
|
728
|
+
toolCalls: NativeToolCall[];
|
|
729
|
+
model?: string;
|
|
730
|
+
}
|
|
731
|
+
|
|
732
|
+
/** Lève une AppError de code 'AI_NO_ANSWER' quand un tour ne donne ni texte ni outil. */
|
|
733
|
+
export function runToolLoop(options: {
|
|
734
|
+
system: string;
|
|
735
|
+
messages: Array<ChatMessage | ToolMessage | Record<string, unknown>>;
|
|
736
|
+
tools?: Array<Record<string, unknown>>;
|
|
737
|
+
turn: (request: { system: string; messages: any[]; tools: Array<Record<string, unknown>> }) => Awaitable<ToolTurn>;
|
|
738
|
+
callTool: (call: NativeToolCall) => Promise<ToolMessage>;
|
|
739
|
+
maxTurns?: number;
|
|
740
|
+
maxMs?: number;
|
|
741
|
+
finalInstruction?: string;
|
|
742
|
+
now?: () => number;
|
|
743
|
+
signal?: AbortSignal;
|
|
744
|
+
}): Promise<{ text: string; turns: number }>;
|
|
745
|
+
|
|
746
|
+
/* ─────────────────── Flux d'évènements (SSE) ─────────────────── */
|
|
747
|
+
|
|
748
|
+
export const EVENT_STREAM_HEADERS: Record<string, string>;
|
|
749
|
+
export function openEventStream(
|
|
750
|
+
res: { statusCode: number; setHeader(name: string, value: string): unknown; flushHeaders(): void; write(chunk: string): unknown; end(): unknown; on(event: 'close', listener: () => void): unknown; writableEnded: boolean },
|
|
751
|
+
options?: { headers?: Record<string, string> }
|
|
752
|
+
): { send(type: string, data: unknown): void; close(): void; signal: AbortSignal };
|
|
753
|
+
|
|
754
|
+
/* ─────────────────── Recherche web ─────────────────── */
|
|
755
|
+
|
|
756
|
+
export interface WebResult { title: string; url: string; snippet: string; date: string | null }
|
|
757
|
+
|
|
758
|
+
/** Lève une erreur de code 'WEB_SEARCH_NO_KEY' (rien n'est demandé) ou 'WEB_SEARCH_FAILED'. */
|
|
759
|
+
export function searchSerper(
|
|
760
|
+
search: { query: string; sites?: string[]; hl?: string; num?: number },
|
|
761
|
+
io: { key: string | null | undefined; fetch: FetchLike; accept?: (result: WebResult, url: URL) => boolean; timeoutMs?: number; endpoint?: string }
|
|
762
|
+
): Promise<WebResult[]>;
|
|
763
|
+
|
|
764
|
+
// Serveur llama.cpp (inférence CPU) : src/llamaCpp.js
|
|
765
|
+
export const DEFAULT_LLAMA_CPP_URL: string;
|
|
766
|
+
export function normalizeLlamaCppUrl(value: string): string;
|
|
767
|
+
|
|
768
|
+
export interface LlamaCppConfigInput {
|
|
769
|
+
/** Base du serveur, avec ou sans `/v1` (défaut http://127.0.0.1:8080). */
|
|
770
|
+
baseUrl?: string;
|
|
771
|
+
apiKey?: string | null;
|
|
772
|
+
model?: string | null;
|
|
773
|
+
timeoutMs?: number;
|
|
774
|
+
healthTimeoutMs?: number;
|
|
775
|
+
}
|
|
776
|
+
export interface LlamaCppConfig {
|
|
777
|
+
readonly id: 'llama.cpp';
|
|
778
|
+
readonly baseUrl: string;
|
|
779
|
+
readonly apiKey: string | null;
|
|
780
|
+
readonly model: string | null;
|
|
781
|
+
readonly timeoutMs: number;
|
|
782
|
+
readonly healthTimeoutMs: number;
|
|
783
|
+
}
|
|
784
|
+
export function createLlamaCppConfig(input?: LlamaCppConfigInput): LlamaCppConfig;
|
|
785
|
+
|
|
786
|
+
export type LocalLlmErrorCode = 'UNREACHABLE' | 'TIMEOUT' | 'UNAUTHORIZED' | 'LOADING' | 'HTTP_ERROR' | 'INVALID_RESPONSE';
|
|
787
|
+
export class LocalLlmError extends Error {
|
|
788
|
+
code: LocalLlmErrorCode;
|
|
789
|
+
status: number | null;
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
export interface LlamaCppChatMessage { role: 'system' | 'user' | 'assistant' | 'tool'; content: string; [key: string]: unknown }
|
|
793
|
+
export interface LlamaCppChatOptions { model?: string; temperature?: number; max_tokens?: number; [key: string]: unknown }
|
|
794
|
+
export interface LlamaCppChatResult {
|
|
795
|
+
text: string;
|
|
796
|
+
finishReason: string | null;
|
|
797
|
+
usage: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number } | null;
|
|
798
|
+
model: string | null;
|
|
799
|
+
}
|
|
800
|
+
export interface LlamaCppHealthState {
|
|
801
|
+
ok: boolean;
|
|
802
|
+
status: 'ok' | 'loading' | 'unauthorized' | 'error' | 'unreachable' | 'timeout';
|
|
803
|
+
latencyMs: number;
|
|
804
|
+
httpStatus?: number;
|
|
805
|
+
message?: string;
|
|
806
|
+
}
|
|
807
|
+
export interface LlamaCppProvider {
|
|
808
|
+
config: LlamaCppConfig;
|
|
809
|
+
health(): Promise<LlamaCppHealthState>;
|
|
810
|
+
waitUntilReady(options?: { timeoutMs?: number; intervalMs?: number }): Promise<LlamaCppHealthState>;
|
|
811
|
+
listModels(): Promise<Array<{ id: string; ownedBy: string | null }>>;
|
|
812
|
+
chat(messages: LlamaCppChatMessage[], options?: LlamaCppChatOptions): Promise<LlamaCppChatResult>;
|
|
813
|
+
chatStream(messages: LlamaCppChatMessage[], options?: LlamaCppChatOptions): AsyncGenerator<string, void, undefined>;
|
|
814
|
+
toOpenAICompatible(): { baseURL: string; apiKey: string; model: string | null };
|
|
815
|
+
}
|
|
816
|
+
export function createLlamaCppProvider(options?: LlamaCppConfigInput & {
|
|
817
|
+
fetch?: (url: string, init: object) => Awaitable<Response>;
|
|
818
|
+
sleep?: (ms: number) => Promise<void>;
|
|
819
|
+
}): LlamaCppProvider;
|
package/src/index.js
CHANGED
|
@@ -13,5 +13,10 @@ module.exports = {
|
|
|
13
13
|
...require('./answerText'),
|
|
14
14
|
...require('./language'),
|
|
15
15
|
...require('./askLimit'),
|
|
16
|
-
...require('./openaiCompatible')
|
|
16
|
+
...require('./openaiCompatible'),
|
|
17
|
+
...require('./llamaCpp'),
|
|
18
|
+
...require('./gemini'),
|
|
19
|
+
...require('./nativeTools'),
|
|
20
|
+
...require('./eventStream'),
|
|
21
|
+
...require('./webSearch')
|
|
17
22
|
};
|