@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.
@@ -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
- call(prompt: string, ctx: Record<string, unknown>, model: ProviderModel): Awaitable<unknown>;
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: string, request?: ProviderRequest, ctx?: Record<string, unknown>): Promise<unknown>;
59
- /** Les entrées sont indexées par "providerId:modelId". */
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 interface RegisteredTool<TParams = Record<string, unknown>, TResult = unknown> extends ToolDefinition<TParams, TResult> {
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
- export function tidyMarkdown(text: unknown, options?: { removeEmoji?: boolean }): string;
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
- export function createOpenAICompatibleProvider(options: {
530
- id: string;
531
- url: string;
532
- getKey: () => Awaitable<string | null | undefined>;
533
- models: ProviderModel[];
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
  };