@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/index.d.ts
CHANGED
|
@@ -12,15 +12,36 @@ export interface ProviderModel {
|
|
|
12
12
|
export interface Provider {
|
|
13
13
|
id: string;
|
|
14
14
|
models: ProviderModel[];
|
|
15
|
-
|
|
15
|
+
/** False for a model running on this machine: the router does not mask for it. */
|
|
16
|
+
external?: boolean;
|
|
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>;
|
|
16
22
|
[key: string]: unknown;
|
|
17
23
|
}
|
|
18
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
|
+
|
|
19
32
|
export interface ProviderRequest {
|
|
20
33
|
complexity?: string;
|
|
21
34
|
estimatedTokens?: number;
|
|
22
35
|
intent?: string;
|
|
23
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;
|
|
24
45
|
[key: string]: unknown;
|
|
25
46
|
}
|
|
26
47
|
|
|
@@ -33,8 +54,34 @@ export interface ProviderRouterConfig {
|
|
|
33
54
|
intentRouting?: Record<string, { preferred?: string[] }>;
|
|
34
55
|
redisKeyPrefix?: string;
|
|
35
56
|
redisUrl?: string;
|
|
57
|
+
/** One circuit per provider: a factory (providerId) => breaker, or a pool. */
|
|
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;
|
|
65
|
+
}
|
|
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;
|
|
36
75
|
}
|
|
37
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
|
+
|
|
38
85
|
export interface ProviderStats {
|
|
39
86
|
provider: string;
|
|
40
87
|
rpm_now: number;
|
|
@@ -46,13 +93,20 @@ export interface ProviderStats {
|
|
|
46
93
|
cooldown: boolean;
|
|
47
94
|
degraded: boolean;
|
|
48
95
|
failures: number;
|
|
96
|
+
/** The provider's circuit state, or null without breakers. */
|
|
97
|
+
circuit: string | null;
|
|
49
98
|
}
|
|
50
99
|
|
|
51
100
|
export interface ProviderRouter {
|
|
52
|
-
ask(prompt:
|
|
53
|
-
/**
|
|
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"). */
|
|
54
105
|
getStats(): Record<string, ProviderStats>;
|
|
106
|
+
/** Oublie repos, dégradations, échecs et usage. */
|
|
107
|
+
reset(): void;
|
|
55
108
|
stop(): void;
|
|
109
|
+
breakers: BreakerPool | null;
|
|
56
110
|
}
|
|
57
111
|
|
|
58
112
|
export function createProviderRouter(config?: ProviderRouterConfig): ProviderRouter;
|
|
@@ -62,6 +116,8 @@ export interface ToolDefinition<TParams = Record<string, unknown>, TResult = unk
|
|
|
62
116
|
description: string;
|
|
63
117
|
type: string;
|
|
64
118
|
roles: string[];
|
|
119
|
+
/** Reaches outside (web search, third-party API): its parameters are masked. */
|
|
120
|
+
external?: boolean;
|
|
65
121
|
params?: Record<string, unknown>;
|
|
66
122
|
handler(params: TParams, ctx: Record<string, unknown>): Awaitable<TResult>;
|
|
67
123
|
}
|
|
@@ -115,6 +171,19 @@ export interface AgentLoopOptions {
|
|
|
115
171
|
* every allowed tool call, unchanged from before.
|
|
116
172
|
*/
|
|
117
173
|
confirmTool?: (toolCall: ToolCall, ctx: Record<string, unknown>) => Awaitable<boolean>;
|
|
174
|
+
/**
|
|
175
|
+
* Masks what leaves for the model, unmasks what comes back. Tools marked
|
|
176
|
+
* `external: true` receive masked parameters.
|
|
177
|
+
*/
|
|
178
|
+
masker?: ReversibleMasker;
|
|
179
|
+
/** A throwing tool becomes { error: 'tool_failed' | 'tool_timeout' } for the model. Default false (throws). */
|
|
180
|
+
reportToolErrors?: boolean;
|
|
181
|
+
toolTimeoutMs?: number;
|
|
182
|
+
/** Time budget for the whole loop. */
|
|
183
|
+
maxMs?: number;
|
|
184
|
+
/** When steps or time run out: one last turn without tools, with this instruction. */
|
|
185
|
+
finalInstruction?: string;
|
|
186
|
+
now?: () => number;
|
|
118
187
|
}
|
|
119
188
|
|
|
120
189
|
export function runAgentLoop(options: AgentLoopOptions): Promise<string>;
|
|
@@ -285,3 +354,383 @@ export function createFormatInstructions(options: {
|
|
|
285
354
|
defaultSurface?: string;
|
|
286
355
|
fallbackLanguage?: string;
|
|
287
356
|
}): FormatInstructions;
|
|
357
|
+
|
|
358
|
+
/* ─────────────────── Circuits ─────────────────── */
|
|
359
|
+
|
|
360
|
+
export interface BreakerLike {
|
|
361
|
+
call<T>(fn: () => Awaitable<T>): Promise<T>;
|
|
362
|
+
status?(): { state?: string; [key: string]: unknown };
|
|
363
|
+
reset?(): void;
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
export interface BreakerPool {
|
|
367
|
+
get(key: string): BreakerLike;
|
|
368
|
+
run<T>(key: string, fn: () => Awaitable<T>): Promise<T>;
|
|
369
|
+
status(): Record<string, unknown>;
|
|
370
|
+
stateOf(key: string): string | null;
|
|
371
|
+
reset(key?: string): void;
|
|
372
|
+
keys(): string[];
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
/** Refuses a factory that returns the same breaker for two keys. */
|
|
376
|
+
export function createBreakerPool(options: { create: (key: string) => BreakerLike }): BreakerPool;
|
|
377
|
+
/** Timeouts, network errors, 408 and 5xx are outages; 429 and other 4xx are not. */
|
|
378
|
+
export function isProviderOutage(error: unknown): boolean;
|
|
379
|
+
export function isCircuitOpen(error: unknown): boolean;
|
|
380
|
+
|
|
381
|
+
/* ─────────────────── Outbound masking ─────────────────── */
|
|
382
|
+
|
|
383
|
+
export interface DetectedEntity {
|
|
384
|
+
text: string;
|
|
385
|
+
type: string;
|
|
386
|
+
score: number;
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
export interface ReversibleMasker {
|
|
390
|
+
mask(text: string, options?: { names?: string[] }): string;
|
|
391
|
+
/** Runs the detector first (keep it local), learns, then masks. */
|
|
392
|
+
maskAsync(text: string, options?: { names?: string[] }): Promise<string>;
|
|
393
|
+
maskDeep<T>(value: T): T;
|
|
394
|
+
unmask(text: string): string;
|
|
395
|
+
unmaskDeep<T>(value: T): T;
|
|
396
|
+
unmaskStream(chunks: AsyncIterable<unknown>): AsyncGenerator<string>;
|
|
397
|
+
detectNames(text: string): Promise<string[]>;
|
|
398
|
+
size(): number;
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
export function createReversibleMasker(options?: {
|
|
402
|
+
names?: string[];
|
|
403
|
+
patterns?: Array<{ type: string; pattern: RegExp }>;
|
|
404
|
+
detect?: (text: string) => Awaitable<DetectedEntity[] | null | undefined>;
|
|
405
|
+
detectTypes?: string[];
|
|
406
|
+
minScore?: number;
|
|
407
|
+
detectMaxChars?: number;
|
|
408
|
+
minLength?: number;
|
|
409
|
+
token?: (type: string, sequence: number) => string;
|
|
410
|
+
typeOf?: (value: string) => string;
|
|
411
|
+
keep?: (value: string) => boolean;
|
|
412
|
+
}): ReversibleMasker;
|
|
413
|
+
|
|
414
|
+
export function withOutboundMasking<Rest extends unknown[], R>(
|
|
415
|
+
masker: ReversibleMasker,
|
|
416
|
+
call: (input: any, ...rest: Rest) => Awaitable<R>
|
|
417
|
+
): (input: unknown, ...rest: Rest) => Promise<R>;
|
|
418
|
+
|
|
419
|
+
export function headWithoutCuttingWords(text: string, max: number): string;
|
|
420
|
+
|
|
421
|
+
/* ─────────────────── Passages in another language ─────────────────── */
|
|
422
|
+
|
|
423
|
+
export interface Passage {
|
|
424
|
+
title?: string;
|
|
425
|
+
text: string;
|
|
426
|
+
lang?: string;
|
|
427
|
+
kind?: string;
|
|
428
|
+
ref?: unknown;
|
|
429
|
+
url?: string;
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
export interface PassageTexts {
|
|
433
|
+
header?: string;
|
|
434
|
+
footer?: string;
|
|
435
|
+
/** Required when a passage can be foreign. `{languages}` becomes the tags found. */
|
|
436
|
+
foreign?: string;
|
|
437
|
+
empty?: string;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
export function primaryLanguage(tag: unknown): string | null;
|
|
441
|
+
export function isForeignLanguage(passageLanguage: unknown, readerLanguage: unknown): boolean;
|
|
442
|
+
export function markForeignPassages(passages: Passage[], options: { lang: string; tag?: (language: string) => string }): { blocks: string[]; languages: string[] };
|
|
443
|
+
/** `passages: null` means the search failed: nothing is said. */
|
|
444
|
+
export function buildPassagesContext(options: { passages: Passage[] | null | undefined; lang: string; texts?: PassageTexts; tag?: (language: string) => string }): string[];
|
|
445
|
+
export function passageSource(passage: Passage, options?: { excerptMax?: number }): Omit<Passage, 'text'> & { excerpt: string };
|
|
446
|
+
|
|
447
|
+
/* ─────────────────── Sources ─────────────────── */
|
|
448
|
+
|
|
449
|
+
export interface SourceLedger<S = Record<string, unknown>> {
|
|
450
|
+
keep(found: S[], data?: unknown): void;
|
|
451
|
+
sources(): S[];
|
|
452
|
+
evidence(): string[];
|
|
453
|
+
size(): number;
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
export function createSourceLedger<S = Record<string, unknown>>(options?: { keyOf?: (source: S) => string }): SourceLedger<S>;
|
|
457
|
+
|
|
458
|
+
export function usedSources<S extends { url?: string; title?: string }, Place = unknown>(
|
|
459
|
+
answer: string,
|
|
460
|
+
sources: S[],
|
|
461
|
+
evidence?: string[],
|
|
462
|
+
options?: {
|
|
463
|
+
references?: (text: string) => Place[];
|
|
464
|
+
sameReference?: (a: Place, b: Place) => boolean;
|
|
465
|
+
ownReference?: (source: S) => Place | null | undefined;
|
|
466
|
+
commonWords?: Iterable<string>;
|
|
467
|
+
minWordLength?: number;
|
|
468
|
+
sharedMin?: number;
|
|
469
|
+
shortEvidence?: number;
|
|
470
|
+
}
|
|
471
|
+
): S[];
|
|
472
|
+
|
|
473
|
+
export interface NliScores { entailment: number; neutral?: number; contradiction: number }
|
|
474
|
+
|
|
475
|
+
export function findContradiction(
|
|
476
|
+
answer: string,
|
|
477
|
+
sources: Array<string | { content?: string; snippet?: string; url?: string; source?: string }>,
|
|
478
|
+
options: {
|
|
479
|
+
compare: (pairs: Array<{ premise: string; hypothesis: string }>) => Awaitable<NliScores[] | null>;
|
|
480
|
+
timeoutMs?: number;
|
|
481
|
+
minWords?: number;
|
|
482
|
+
sharedMin?: number;
|
|
483
|
+
maxPairs?: number;
|
|
484
|
+
contradictionMin?: number;
|
|
485
|
+
entailmentMax?: number;
|
|
486
|
+
commonWords?: Iterable<string>;
|
|
487
|
+
}
|
|
488
|
+
): Promise<{ contradicts: boolean; sentence: string | null; source: string | null } | null>;
|
|
489
|
+
|
|
490
|
+
export function factualSentences(answer: string, minWords: number): string[];
|
|
491
|
+
|
|
492
|
+
export function rerankResults<R, S, F extends { results: R[]; sources?: S[] }>(
|
|
493
|
+
query: string,
|
|
494
|
+
found: F,
|
|
495
|
+
options: {
|
|
496
|
+
score: (query: string, passages: string[]) => Awaitable<number[] | null>;
|
|
497
|
+
passageOf?: (result: R) => string;
|
|
498
|
+
sourceMatches?: (source: S, result: R) => boolean;
|
|
499
|
+
}
|
|
500
|
+
): Promise<F>;
|
|
501
|
+
|
|
502
|
+
/* ─────────────────── Answer text ─────────────────── */
|
|
503
|
+
|
|
504
|
+
export function plainText(text: unknown): string;
|
|
505
|
+
/** `remove` : des expressions globales retirées après les marques (ce que l'app ne montre jamais). */
|
|
506
|
+
export function tidyMarkdown(text: unknown, options?: { removeEmoji?: boolean; remove?: RegExp[] }): string;
|
|
507
|
+
/** Un texte coupé ramené à sa dernière phrase entière. */
|
|
508
|
+
export function wholeSentences(text: unknown, options?: { marks?: string[] }): string;
|
|
509
|
+
export function isFaithfulQuotation(quoted: string, source: string): boolean;
|
|
510
|
+
export function verifyQuotations<Refs = unknown>(text: string, options: {
|
|
511
|
+
findReferences: (text: string) => Awaitable<Array<{ start: number; end: number; refs: Refs }>>;
|
|
512
|
+
resolve: (refs: Refs) => Awaitable<string | null | undefined>;
|
|
513
|
+
}): Promise<string>;
|
|
514
|
+
|
|
515
|
+
/* ─────────────────── Reply language ─────────────────── */
|
|
516
|
+
|
|
517
|
+
export interface LanguageDetector {
|
|
518
|
+
byWords(text: string): string | null;
|
|
519
|
+
reply(text: string, appLanguage: string): Promise<string>;
|
|
520
|
+
languages: string[];
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
export function createLanguageDetector(options: {
|
|
524
|
+
words: Record<string, string[]>;
|
|
525
|
+
identify?: (text: string) => Awaitable<{ language: string; confidence: number }>;
|
|
526
|
+
fallback?: string;
|
|
527
|
+
confidenceMin?: number;
|
|
528
|
+
shortConfidenceMin?: number;
|
|
529
|
+
shortWords?: number;
|
|
530
|
+
lead?: number;
|
|
531
|
+
maxChars?: number;
|
|
532
|
+
}): LanguageDetector;
|
|
533
|
+
|
|
534
|
+
/* ─────────────────── Ask limit ─────────────────── */
|
|
535
|
+
|
|
536
|
+
export interface AskLimitVerdict { allowed: boolean; remaining: number; retryInMs: number }
|
|
537
|
+
|
|
538
|
+
export interface AskLimit {
|
|
539
|
+
/** Throws a 429 AppError with `code` and `retryInMs` past the limit. */
|
|
540
|
+
take(subject: string | number, now?: number): AskLimitVerdict;
|
|
541
|
+
peek(subject: string | number, now?: number): AskLimitVerdict;
|
|
542
|
+
reset(subject?: string | number): void;
|
|
543
|
+
size(): number;
|
|
544
|
+
sweep(now: number): void;
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
export function createAskLimit(options: { max: number; windowMs: number; code?: string; sweepEvery?: number }): AskLimit;
|
|
548
|
+
|
|
549
|
+
/* ─────────────────── OpenAI-compatible endpoints ─────────────────── */
|
|
550
|
+
|
|
551
|
+
export interface ChatMessage {
|
|
552
|
+
role: 'user' | 'assistant' | 'tool' | 'system';
|
|
553
|
+
text?: string;
|
|
554
|
+
content?: string;
|
|
555
|
+
images?: Array<{ mimeType: string; data: string }>;
|
|
556
|
+
toolCalls?: Array<{ id: string; name: string; args: unknown }>;
|
|
557
|
+
toolCallId?: string;
|
|
558
|
+
result?: unknown;
|
|
559
|
+
}
|
|
560
|
+
|
|
561
|
+
export interface ChatToolCall {
|
|
562
|
+
id: string;
|
|
563
|
+
name: string;
|
|
564
|
+
args: Record<string, unknown> | null;
|
|
565
|
+
/** The model sent arguments that are not a JSON object. */
|
|
566
|
+
invalid?: true;
|
|
567
|
+
/** Pourquoi : 'not_json' (illisible) ou 'not_object'. */
|
|
568
|
+
invalidReason?: 'not_json' | 'not_object';
|
|
569
|
+
/** L'erreur de lecture, pour 'not_json'. */
|
|
570
|
+
invalidDetail?: string;
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
export type FetchLike = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; json(): Promise<any> }>;
|
|
574
|
+
|
|
575
|
+
export function askChatModel(
|
|
576
|
+
target: { url: string; key: string; model: string; extra?: Record<string, unknown> },
|
|
577
|
+
request: { system?: string; messages: ChatMessage[]; tools?: Array<Record<string, unknown>>; maxTokens?: number; temperature?: number },
|
|
578
|
+
io: { fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number }
|
|
579
|
+
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
|
|
580
|
+
|
|
581
|
+
export function readToolArguments(raw: unknown): { args: Record<string, unknown> | null; invalid: boolean; reason?: 'not_json' | 'not_object'; detail?: string };
|
|
582
|
+
|
|
583
|
+
/** Les appels d'outil écrits dans un texte (<function=…>, <tool_call>{…}</tool_call>), relus. */
|
|
584
|
+
export function readWrittenToolCalls(text: string): Array<{ id: string; name: string; args: Record<string, unknown> }>;
|
|
585
|
+
/** Le raisonnement entre balises think retiré, même ouvert sans fin ou fermé sans ouverture. */
|
|
586
|
+
export function withoutThinking(content: unknown): string;
|
|
587
|
+
|
|
588
|
+
export interface ChatRequest {
|
|
589
|
+
system?: string;
|
|
590
|
+
messages: ChatMessage[];
|
|
591
|
+
tools?: Array<Record<string, unknown>>;
|
|
592
|
+
maxTokens?: number;
|
|
593
|
+
temperature?: number;
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
/** Ce qu'un fournisseur `detailed` rend au routeur. */
|
|
597
|
+
export interface DetailedAnswer {
|
|
598
|
+
text: string | null;
|
|
599
|
+
toolCalls: ChatToolCall[];
|
|
600
|
+
cut: boolean;
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
export interface ChatProviderOptions {
|
|
604
|
+
getKey: (ctx: Record<string, unknown>) => Awaitable<string | null | undefined>;
|
|
605
|
+
models?: ProviderModel[];
|
|
606
|
+
/** `ctx.fetch` le remplace pour un appel. */
|
|
607
|
+
fetch: FetchLike;
|
|
608
|
+
timeoutMs?: number;
|
|
609
|
+
lane?: (ctx: Record<string, unknown>) => string | null | undefined;
|
|
610
|
+
/** Vrai : l'appel rend { text, toolCalls, cut } au lieu du texte seul. */
|
|
611
|
+
detailed?: boolean;
|
|
612
|
+
toRequest?: (prompt: any, ctx: Record<string, unknown>) => ChatRequest;
|
|
613
|
+
}
|
|
614
|
+
|
|
615
|
+
export function createOpenAICompatibleProvider(options: ChatProviderOptions & {
|
|
616
|
+
id: string;
|
|
617
|
+
url: string | ((ctx: Record<string, unknown>) => string | null | undefined);
|
|
618
|
+
external?: boolean;
|
|
619
|
+
extra?: Record<string, unknown>;
|
|
620
|
+
}): Provider;
|
|
621
|
+
|
|
622
|
+
/* ─────────────────── Gemini ─────────────────── */
|
|
623
|
+
|
|
624
|
+
export function askGeminiModel(
|
|
625
|
+
model: string,
|
|
626
|
+
request: ChatRequest,
|
|
627
|
+
io: { key: string; fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number; endpoint?: string; noSystemInstruction?: (model: string) => boolean }
|
|
628
|
+
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
|
|
629
|
+
|
|
630
|
+
export function createGeminiProvider(options: ChatProviderOptions & {
|
|
631
|
+
id?: string;
|
|
632
|
+
endpoint?: string;
|
|
633
|
+
/** Défaut : les modèles Gemma, qui ne prennent pas de consigne système. */
|
|
634
|
+
noSystemInstruction?: (model: string) => boolean;
|
|
635
|
+
}): Provider;
|
|
636
|
+
|
|
637
|
+
/* ─────────────────── Outils natifs et leur boucle ─────────────────── */
|
|
638
|
+
|
|
639
|
+
export type NativeToolKind = 'read' | 'write' | 'confirm' | string;
|
|
640
|
+
|
|
641
|
+
export interface NativeToolResult {
|
|
642
|
+
data?: unknown;
|
|
643
|
+
sources?: Array<Record<string, unknown>>;
|
|
644
|
+
card?: Record<string, unknown>;
|
|
645
|
+
undo?: unknown;
|
|
646
|
+
[key: string]: unknown;
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
export interface NativeTool<Ctx = Record<string, unknown>> {
|
|
650
|
+
name: string;
|
|
651
|
+
description: string;
|
|
652
|
+
parameters: { type: 'object'; [key: string]: unknown };
|
|
653
|
+
kind: NativeToolKind;
|
|
654
|
+
summary?: (args: Record<string, unknown>) => Record<string, string | number>;
|
|
655
|
+
run(args: Record<string, unknown>, ctx: Ctx & { signal: AbortSignal }): Awaitable<NativeToolResult | null | undefined>;
|
|
656
|
+
perform?(args: Record<string, unknown>, ctx: Ctx): Awaitable<NativeToolResult | null | undefined>;
|
|
657
|
+
undo?(undo: unknown, ctx: Ctx): Awaitable<unknown>;
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
export const NATIVE_TOOL_KINDS: string[];
|
|
661
|
+
export function validateNativeTools<T extends NativeTool<any>>(tools: T[], options?: { kinds?: string[]; requireSummary?: boolean }): T[];
|
|
662
|
+
export function toolSpecs(tools: NativeTool<any>[]): Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
|
|
663
|
+
export function stepParams(tool: NativeTool<any> | null | undefined, args: unknown, options?: { max?: number }): Record<string, string | number>;
|
|
664
|
+
|
|
665
|
+
export interface NativeToolCall {
|
|
666
|
+
id: string;
|
|
667
|
+
name: string;
|
|
668
|
+
args: Record<string, unknown> | null;
|
|
669
|
+
invalid?: boolean;
|
|
670
|
+
invalidReason?: 'not_json' | 'not_object';
|
|
671
|
+
invalidDetail?: string;
|
|
672
|
+
}
|
|
673
|
+
|
|
674
|
+
export interface ToolMessage {
|
|
675
|
+
role: 'tool';
|
|
676
|
+
toolCallId: string;
|
|
677
|
+
name: string;
|
|
678
|
+
result: unknown;
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
export function createToolCaller<Ctx = Record<string, unknown>>(options: {
|
|
682
|
+
tools: Map<string, NativeTool<Ctx>> | NativeTool<Ctx>[];
|
|
683
|
+
context?: Ctx;
|
|
684
|
+
signal?: AbortSignal;
|
|
685
|
+
timeoutMs?: number;
|
|
686
|
+
now?: () => number;
|
|
687
|
+
emit?: (type: 'step' | 'step_done', data: Record<string, unknown>) => void;
|
|
688
|
+
keep?: (sources: unknown, data: unknown) => void;
|
|
689
|
+
record?: (entry: { tool: NativeTool<Ctx>; args: Record<string, unknown> | null; found: NativeToolResult }) => Awaitable<void>;
|
|
690
|
+
onCall?: (stats: { name: string; ms: number; ok: boolean }) => void;
|
|
691
|
+
resultMax?: number;
|
|
692
|
+
messages?: {
|
|
693
|
+
unknownTool?: (name: string) => string;
|
|
694
|
+
timeout?: () => string;
|
|
695
|
+
invalidArguments?: (call: { name: string; invalidReason?: string; invalidDetail?: string }) => string;
|
|
696
|
+
waiting?: string;
|
|
697
|
+
};
|
|
698
|
+
}): (call: NativeToolCall) => Promise<ToolMessage>;
|
|
699
|
+
|
|
700
|
+
export interface ToolTurn {
|
|
701
|
+
text: string | null;
|
|
702
|
+
toolCalls: NativeToolCall[];
|
|
703
|
+
model?: string;
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
/** Lève une AppError de code 'AI_NO_ANSWER' quand un tour ne donne ni texte ni outil. */
|
|
707
|
+
export function runToolLoop(options: {
|
|
708
|
+
system: string;
|
|
709
|
+
messages: Array<ChatMessage | ToolMessage | Record<string, unknown>>;
|
|
710
|
+
tools?: Array<Record<string, unknown>>;
|
|
711
|
+
turn: (request: { system: string; messages: any[]; tools: Array<Record<string, unknown>> }) => Awaitable<ToolTurn>;
|
|
712
|
+
callTool: (call: NativeToolCall) => Promise<ToolMessage>;
|
|
713
|
+
maxTurns?: number;
|
|
714
|
+
maxMs?: number;
|
|
715
|
+
finalInstruction?: string;
|
|
716
|
+
now?: () => number;
|
|
717
|
+
signal?: AbortSignal;
|
|
718
|
+
}): Promise<{ text: string; turns: number }>;
|
|
719
|
+
|
|
720
|
+
/* ─────────────────── Flux d'évènements (SSE) ─────────────────── */
|
|
721
|
+
|
|
722
|
+
export const EVENT_STREAM_HEADERS: Record<string, string>;
|
|
723
|
+
export function openEventStream(
|
|
724
|
+
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 },
|
|
725
|
+
options?: { headers?: Record<string, string> }
|
|
726
|
+
): { send(type: string, data: unknown): void; close(): void; signal: AbortSignal };
|
|
727
|
+
|
|
728
|
+
/* ─────────────────── Recherche web ─────────────────── */
|
|
729
|
+
|
|
730
|
+
export interface WebResult { title: string; url: string; snippet: string; date: string | null }
|
|
731
|
+
|
|
732
|
+
/** Lève une erreur de code 'WEB_SEARCH_NO_KEY' (rien n'est demandé) ou 'WEB_SEARCH_FAILED'. */
|
|
733
|
+
export function searchSerper(
|
|
734
|
+
search: { query: string; sites?: string[]; hl?: string; num?: number },
|
|
735
|
+
io: { key: string | null | undefined; fetch: FetchLike; accept?: (result: WebResult, url: URL) => boolean; timeoutMs?: number; endpoint?: string }
|
|
736
|
+
): Promise<WebResult[]>;
|
package/src/index.js
CHANGED
|
@@ -5,5 +5,17 @@ module.exports = {
|
|
|
5
5
|
...require('./pendingActions'),
|
|
6
6
|
...require('./fallback'),
|
|
7
7
|
...require('./responseCleaner'),
|
|
8
|
-
...require('./formatInstructions')
|
|
8
|
+
...require('./formatInstructions'),
|
|
9
|
+
...require('./breakers'),
|
|
10
|
+
...require('./masking'),
|
|
11
|
+
...require('./passages'),
|
|
12
|
+
...require('./sources'),
|
|
13
|
+
...require('./answerText'),
|
|
14
|
+
...require('./language'),
|
|
15
|
+
...require('./askLimit'),
|
|
16
|
+
...require('./openaiCompatible'),
|
|
17
|
+
...require('./gemini'),
|
|
18
|
+
...require('./nativeTools'),
|
|
19
|
+
...require('./eventStream'),
|
|
20
|
+
...require('./webSearch')
|
|
9
21
|
};
|
package/src/language.js
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The language to answer in.
|
|
3
|
+
*
|
|
4
|
+
* The language set in the app stays the rule; a message CLEARLY written in
|
|
5
|
+
* another supported language is answered in that one. Two readers:
|
|
6
|
+
*
|
|
7
|
+
* 1. the small words — articles, pronouns, the few verbs of every sentence
|
|
8
|
+
* — which decide a short message ("merci", "ok") that no statistical
|
|
9
|
+
* identifier can;
|
|
10
|
+
* 2. an identifier (fastText's lid.176 or anything alike), injected, trusted
|
|
11
|
+
* only above a confidence — a far higher one for a message of two words.
|
|
12
|
+
*
|
|
13
|
+
* Anything else — an unsupported language, a message too short to tell, the
|
|
14
|
+
* identifier out of reach — keeps the app's language. Guessing wrong switches
|
|
15
|
+
* the whole answer, the voice and the sources into a language the person did
|
|
16
|
+
* not ask for.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* @param {object} options
|
|
21
|
+
* @param {Record<string, string[]>} options.words language -> its small words (lower case).
|
|
22
|
+
* @param {Function} [options.identify] async (text) => { language, confidence }.
|
|
23
|
+
* @param {string} [options.fallback] when the app language is not supported. Default: the first language.
|
|
24
|
+
* @param {number} [options.confidenceMin] Default 0.5.
|
|
25
|
+
* @param {number} [options.shortConfidenceMin] for fewer than `shortWords` words. Default 0.9.
|
|
26
|
+
* @param {number} [options.shortWords] Default 3.
|
|
27
|
+
* @param {number} [options.lead] how far the small words must lean to decide alone. Default 2.
|
|
28
|
+
* @param {number} [options.maxChars] text handed to the identifier. Default 2000.
|
|
29
|
+
*/
|
|
30
|
+
function createLanguageDetector(options = {}) {
|
|
31
|
+
const entries = Object.entries(options.words || {});
|
|
32
|
+
if (entries.length < 2) throw new Error('createLanguageDetector requires small words for at least two languages.');
|
|
33
|
+
const sets = new Map(entries.map(([language, list]) => [language, new Set(list.map((word) => String(word).toLowerCase().replace(/’/g, "'")))]));
|
|
34
|
+
const languages = [...sets.keys()];
|
|
35
|
+
const identify = typeof options.identify === 'function' ? options.identify : null;
|
|
36
|
+
const fallbackLanguage = languages.includes(options.fallback) ? options.fallback : languages[0];
|
|
37
|
+
const confidenceMin = options.confidenceMin === undefined ? 0.5 : options.confidenceMin;
|
|
38
|
+
const shortConfidenceMin = options.shortConfidenceMin === undefined ? 0.9 : options.shortConfidenceMin;
|
|
39
|
+
const shortWords = options.shortWords || 3;
|
|
40
|
+
const lead = options.lead || 2;
|
|
41
|
+
const maxChars = options.maxChars || 2000;
|
|
42
|
+
|
|
43
|
+
/** The small words' vote: a language, or null when they do not lean clearly. */
|
|
44
|
+
function byWords(text) {
|
|
45
|
+
const words = (String(text === null || text === undefined ? '' : text).toLowerCase().match(/[\p{L}'’-]+/gu) || [])
|
|
46
|
+
.map((word) => word.replace(/’/g, "'"));
|
|
47
|
+
const counts = languages.map((language) => ({ language, count: words.filter((word) => sets.get(language).has(word)).length }))
|
|
48
|
+
.sort((a, b) => b.count - a.count);
|
|
49
|
+
const [first, second] = counts;
|
|
50
|
+
if (!first.count) return null;
|
|
51
|
+
if (first.count >= second.count + lead) return first.language;
|
|
52
|
+
/* One or two words, all from one language: "merci", "thank you". */
|
|
53
|
+
if (words.length <= 2 && second.count === 0) return first.language;
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* @param {string} text what the person wrote.
|
|
59
|
+
* @param {string} appLanguage the language set in the app.
|
|
60
|
+
*/
|
|
61
|
+
async function reply(text, appLanguage) {
|
|
62
|
+
const fallback = languages.includes(appLanguage) ? appLanguage : fallbackLanguage;
|
|
63
|
+
const written = String(text === null || text === undefined ? '' : text).trim();
|
|
64
|
+
if (!written) return fallback;
|
|
65
|
+
const words = byWords(written);
|
|
66
|
+
if (identify) {
|
|
67
|
+
try {
|
|
68
|
+
const found = await identify(written.slice(0, maxChars));
|
|
69
|
+
const language = found && typeof found.language === 'string' ? found.language.toLowerCase() : null;
|
|
70
|
+
const confidence = Number(found && found.confidence) || 0;
|
|
71
|
+
const short = (written.match(/\p{L}+/gu) || []).length < shortWords;
|
|
72
|
+
if (confidence >= (short ? shortConfidenceMin : confidenceMin)) {
|
|
73
|
+
return languages.includes(language) ? language : (words || fallback);
|
|
74
|
+
}
|
|
75
|
+
} catch (_error) {
|
|
76
|
+
/* The identifier out of reach: the small words alone. */
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
return words || fallback;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
return { byWords, reply, languages };
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
module.exports = { createLanguageDetector };
|