@astratra/ai 1.2.0 → 1.4.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 +208 -0
- package/package.json +2 -1
- package/src/agentLoop.js +88 -11
- package/src/answerText.js +117 -0
- package/src/askLimit.js +69 -0
- package/src/breakers.js +97 -0
- package/src/formatInstructions.js +99 -0
- package/src/index.d.ts +324 -0
- package/src/index.js +11 -1
- package/src/language.js +85 -0
- package/src/masking.js +279 -0
- package/src/openaiCompatible.js +170 -0
- package/src/passages.js +101 -0
- package/src/providerRouter.js +77 -11
- package/src/responseCleaner.js +337 -0
- package/src/sources.js +243 -0
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Telling the model where its reply will be displayed.
|
|
3
|
+
*
|
|
4
|
+
* The same answer goes to a 1,400-pixel desktop console and to a 390-point
|
|
5
|
+
* phone. A model that is not told writes for the screen it imagines, and ships
|
|
6
|
+
* five-column tables that a phone renders as crushed columns or a horizontal
|
|
7
|
+
* scroll nobody finds.
|
|
8
|
+
*
|
|
9
|
+
* Why the default surface is the PHONE: guessing small wrongly costs a list
|
|
10
|
+
* where a table would have fit — still readable. Guessing large wrongly costs an
|
|
11
|
+
* unreadable table on the phone. The risk is not symmetric.
|
|
12
|
+
*
|
|
13
|
+
* Why the paragraph rule is mandatory: without it models start a sentence and
|
|
14
|
+
* leave it hanging, or pack a compact block with no breathing room, and put
|
|
15
|
+
* horizontal rules (---) between ideas. The rule must reach EVERY surface — so a
|
|
16
|
+
* language pack without it is refused at creation, not discovered on a screen.
|
|
17
|
+
*
|
|
18
|
+
* All wording is supplied by the caller, per language. Templates may use
|
|
19
|
+
* {surface} (that language's name for the surface) and {columns}.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
const DEFAULT_SURFACES = {
|
|
23
|
+
phone: { columns: 3, narrow: true, aliases: ['mobile', 'ios', 'android'] },
|
|
24
|
+
tablet: { columns: 4, narrow: false, aliases: ['ipad'] },
|
|
25
|
+
desktop: { columns: 6, narrow: false, aliases: ['web', 'browser'] }
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
function fill(template, values) {
|
|
29
|
+
return String(template).replace(/\{(\w+)\}/g, (whole, name) => (
|
|
30
|
+
Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : whole
|
|
31
|
+
));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* @param {object} options
|
|
36
|
+
* @param {Record<string, object>} options.languages language -> pack:
|
|
37
|
+
* { paragraphs (required), heading?, intro?, table?, narrow?, wide?,
|
|
38
|
+
* rules?: string[], surfaceNames?: Record<surfaceId, string> }
|
|
39
|
+
* @param {Record<string, {columns: number, narrow?: boolean, aliases?: string[]}>} [options.surfaces]
|
|
40
|
+
* @param {string} [options.defaultSurface='phone']
|
|
41
|
+
* @param {string} [options.fallbackLanguage]
|
|
42
|
+
*/
|
|
43
|
+
function createFormatInstructions(options = {}) {
|
|
44
|
+
const surfaces = options.surfaces || DEFAULT_SURFACES;
|
|
45
|
+
const defaultSurface = options.defaultSurface || 'phone';
|
|
46
|
+
if (!surfaces[defaultSurface]) {
|
|
47
|
+
throw new Error(`createFormatInstructions: unknown defaultSurface "${defaultSurface}".`);
|
|
48
|
+
}
|
|
49
|
+
const languages = options.languages || {};
|
|
50
|
+
const names = Object.keys(languages);
|
|
51
|
+
if (!names.length) throw new Error('createFormatInstructions requires at least one language pack.');
|
|
52
|
+
for (const name of names) {
|
|
53
|
+
const pack = languages[name];
|
|
54
|
+
if (!pack || typeof pack.paragraphs !== 'string' || !pack.paragraphs.trim()) {
|
|
55
|
+
throw new Error(`createFormatInstructions: language "${name}" has no paragraphs rule.`);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
const fallbackLanguage = options.fallbackLanguage && languages[options.fallbackLanguage]
|
|
59
|
+
? options.fallbackLanguage
|
|
60
|
+
: names[0];
|
|
61
|
+
|
|
62
|
+
const aliasIndex = new Map();
|
|
63
|
+
for (const [id, surface] of Object.entries(surfaces)) {
|
|
64
|
+
aliasIndex.set(id.toLowerCase(), id);
|
|
65
|
+
for (const alias of surface.aliases || []) aliasIndex.set(String(alias).toLowerCase(), id);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Any client-sent value maps to a known surface; missing or unknown means the default. */
|
|
69
|
+
function normalizeSurface(value) {
|
|
70
|
+
if (typeof value !== 'string') return defaultSurface;
|
|
71
|
+
return aliasIndex.get(value.trim().toLowerCase()) || defaultSurface;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function build(surfaceValue, language) {
|
|
75
|
+
const id = normalizeSurface(surfaceValue);
|
|
76
|
+
const surface = surfaces[id];
|
|
77
|
+
const pack = languages[language] || languages[fallbackLanguage];
|
|
78
|
+
const values = {
|
|
79
|
+
surface: (pack.surfaceNames && pack.surfaceNames[id]) || id,
|
|
80
|
+
columns: surface.columns
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
const lines = [];
|
|
84
|
+
if (pack.intro) lines.push(fill(pack.intro, values));
|
|
85
|
+
const bullets = [];
|
|
86
|
+
if (pack.table) bullets.push(pack.table);
|
|
87
|
+
const sizeRule = surface.narrow ? pack.narrow : pack.wide;
|
|
88
|
+
if (sizeRule) bullets.push(sizeRule);
|
|
89
|
+
bullets.push(pack.paragraphs);
|
|
90
|
+
for (const rule of pack.rules || []) bullets.push(rule);
|
|
91
|
+
lines.push(bullets.map((b) => `- ${fill(b, values)}`).join('\n'));
|
|
92
|
+
|
|
93
|
+
return (pack.heading ? `${fill(pack.heading, values)}\n` : '') + lines.join('\n\n');
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
return { build, normalizeSurface, surfaces: Object.keys(surfaces), languages: names };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
module.exports = { createFormatInstructions, DEFAULT_SURFACES };
|
package/src/index.d.ts
CHANGED
|
@@ -12,6 +12,8 @@ export interface ProviderModel {
|
|
|
12
12
|
export interface Provider {
|
|
13
13
|
id: string;
|
|
14
14
|
models: ProviderModel[];
|
|
15
|
+
/** False for a model running on this machine: the router does not mask for it. */
|
|
16
|
+
external?: boolean;
|
|
15
17
|
call(prompt: string, ctx: Record<string, unknown>, model: ProviderModel): Awaitable<unknown>;
|
|
16
18
|
[key: string]: unknown;
|
|
17
19
|
}
|
|
@@ -33,6 +35,8 @@ export interface ProviderRouterConfig {
|
|
|
33
35
|
intentRouting?: Record<string, { preferred?: string[] }>;
|
|
34
36
|
redisKeyPrefix?: string;
|
|
35
37
|
redisUrl?: string;
|
|
38
|
+
/** One circuit per provider: a factory (providerId) => breaker, or a pool. */
|
|
39
|
+
breakers?: ((providerId: string) => BreakerLike) | BreakerPool;
|
|
36
40
|
}
|
|
37
41
|
|
|
38
42
|
export interface ProviderStats {
|
|
@@ -46,6 +50,8 @@ export interface ProviderStats {
|
|
|
46
50
|
cooldown: boolean;
|
|
47
51
|
degraded: boolean;
|
|
48
52
|
failures: number;
|
|
53
|
+
/** The provider's circuit state, or null without breakers. */
|
|
54
|
+
circuit: string | null;
|
|
49
55
|
}
|
|
50
56
|
|
|
51
57
|
export interface ProviderRouter {
|
|
@@ -53,6 +59,7 @@ export interface ProviderRouter {
|
|
|
53
59
|
/** Les entrées sont indexées par "providerId:modelId". */
|
|
54
60
|
getStats(): Record<string, ProviderStats>;
|
|
55
61
|
stop(): void;
|
|
62
|
+
breakers: BreakerPool | null;
|
|
56
63
|
}
|
|
57
64
|
|
|
58
65
|
export function createProviderRouter(config?: ProviderRouterConfig): ProviderRouter;
|
|
@@ -62,6 +69,8 @@ export interface ToolDefinition<TParams = Record<string, unknown>, TResult = unk
|
|
|
62
69
|
description: string;
|
|
63
70
|
type: string;
|
|
64
71
|
roles: string[];
|
|
72
|
+
/** Reaches outside (web search, third-party API): its parameters are masked. */
|
|
73
|
+
external?: boolean;
|
|
65
74
|
params?: Record<string, unknown>;
|
|
66
75
|
handler(params: TParams, ctx: Record<string, unknown>): Awaitable<TResult>;
|
|
67
76
|
}
|
|
@@ -115,6 +124,19 @@ export interface AgentLoopOptions {
|
|
|
115
124
|
* every allowed tool call, unchanged from before.
|
|
116
125
|
*/
|
|
117
126
|
confirmTool?: (toolCall: ToolCall, ctx: Record<string, unknown>) => Awaitable<boolean>;
|
|
127
|
+
/**
|
|
128
|
+
* Masks what leaves for the model, unmasks what comes back. Tools marked
|
|
129
|
+
* `external: true` receive masked parameters.
|
|
130
|
+
*/
|
|
131
|
+
masker?: ReversibleMasker;
|
|
132
|
+
/** A throwing tool becomes { error: 'tool_failed' | 'tool_timeout' } for the model. Default false (throws). */
|
|
133
|
+
reportToolErrors?: boolean;
|
|
134
|
+
toolTimeoutMs?: number;
|
|
135
|
+
/** Time budget for the whole loop. */
|
|
136
|
+
maxMs?: number;
|
|
137
|
+
/** When steps or time run out: one last turn without tools, with this instruction. */
|
|
138
|
+
finalInstruction?: string;
|
|
139
|
+
now?: () => number;
|
|
118
140
|
}
|
|
119
141
|
|
|
120
142
|
export function runAgentLoop(options: AgentLoopOptions): Promise<string>;
|
|
@@ -213,3 +235,305 @@ export function createDeterministicFallback<Input = Record<string, unknown>>(opt
|
|
|
213
235
|
classify?: (input: Input) => string | null | undefined;
|
|
214
236
|
markDegraded?: (answer: Record<string, unknown>) => Record<string, unknown>;
|
|
215
237
|
}): DeterministicFallback<Input>;
|
|
238
|
+
|
|
239
|
+
/** A literal word (escaped) or a RegExp whose source is used as-is. */
|
|
240
|
+
export type VocabularyEntry = string | RegExp;
|
|
241
|
+
|
|
242
|
+
export interface CleanerVocabulary {
|
|
243
|
+
/** Wrapper keys whose string value IS the answer ({"response": "..."}). */
|
|
244
|
+
payloadKeys?: VocabularyEntry[];
|
|
245
|
+
/** Object keys rendered as a bold heading when JSON becomes prose. */
|
|
246
|
+
titleKeys?: string[];
|
|
247
|
+
/** Labels removed at the start of a line only ("**introduction** : ..."). */
|
|
248
|
+
lineLabels?: VocabularyEntry[];
|
|
249
|
+
/** Form-like labels removed anywhere they are followed by ":", "-" or "—". */
|
|
250
|
+
inlineLabels?: VocabularyEntry[];
|
|
251
|
+
/** Labels removed when alone on a line or leading one, bold or not, colon or not. */
|
|
252
|
+
headingLabels?: VocabularyEntry[];
|
|
253
|
+
reasoningLabels?: VocabularyEntry[];
|
|
254
|
+
reasoningStarters?: VocabularyEntry[];
|
|
255
|
+
finalMarkers?: VocabularyEntry[];
|
|
256
|
+
planningStarters?: VocabularyEntry[];
|
|
257
|
+
leadingFillers?: VocabularyEntry[];
|
|
258
|
+
annotationMarkers?: VocabularyEntry[];
|
|
259
|
+
/** Robotic closings, removed only at the very end of the reply. */
|
|
260
|
+
closingPhrases?: VocabularyEntry[];
|
|
261
|
+
openers?: VocabularyEntry[];
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
export interface ResponseCleaner {
|
|
265
|
+
clean(text: string | null | undefined, options?: { language?: string }): string;
|
|
266
|
+
jsonToProse(value: unknown, language?: string): string;
|
|
267
|
+
languages: string[];
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
export function createResponseCleaner(options?: {
|
|
271
|
+
shared?: CleanerVocabulary;
|
|
272
|
+
languages?: Record<string, CleanerVocabulary>;
|
|
273
|
+
fallbackLanguage?: string;
|
|
274
|
+
maxClosingPasses?: number;
|
|
275
|
+
}): ResponseCleaner;
|
|
276
|
+
|
|
277
|
+
export interface FormatSurface {
|
|
278
|
+
columns: number;
|
|
279
|
+
narrow?: boolean;
|
|
280
|
+
aliases?: string[];
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
export interface FormatLanguagePack {
|
|
284
|
+
/** Mandatory: the paragraph rule reaches every surface. */
|
|
285
|
+
paragraphs: string;
|
|
286
|
+
heading?: string;
|
|
287
|
+
intro?: string;
|
|
288
|
+
table?: string;
|
|
289
|
+
narrow?: string;
|
|
290
|
+
wide?: string;
|
|
291
|
+
rules?: string[];
|
|
292
|
+
surfaceNames?: Record<string, string>;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
export interface FormatInstructions {
|
|
296
|
+
build(surface: unknown, language?: string): string;
|
|
297
|
+
normalizeSurface(surface: unknown): string;
|
|
298
|
+
surfaces: string[];
|
|
299
|
+
languages: string[];
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
export const DEFAULT_SURFACES: Record<'phone' | 'tablet' | 'desktop', FormatSurface>;
|
|
303
|
+
|
|
304
|
+
export function createFormatInstructions(options: {
|
|
305
|
+
languages: Record<string, FormatLanguagePack>;
|
|
306
|
+
surfaces?: Record<string, FormatSurface>;
|
|
307
|
+
defaultSurface?: string;
|
|
308
|
+
fallbackLanguage?: string;
|
|
309
|
+
}): FormatInstructions;
|
|
310
|
+
|
|
311
|
+
/* ─────────────────── Circuits ─────────────────── */
|
|
312
|
+
|
|
313
|
+
export interface BreakerLike {
|
|
314
|
+
call<T>(fn: () => Awaitable<T>): Promise<T>;
|
|
315
|
+
status?(): { state?: string; [key: string]: unknown };
|
|
316
|
+
reset?(): void;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
export interface BreakerPool {
|
|
320
|
+
get(key: string): BreakerLike;
|
|
321
|
+
run<T>(key: string, fn: () => Awaitable<T>): Promise<T>;
|
|
322
|
+
status(): Record<string, unknown>;
|
|
323
|
+
stateOf(key: string): string | null;
|
|
324
|
+
reset(key?: string): void;
|
|
325
|
+
keys(): string[];
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** Refuses a factory that returns the same breaker for two keys. */
|
|
329
|
+
export function createBreakerPool(options: { create: (key: string) => BreakerLike }): BreakerPool;
|
|
330
|
+
/** Timeouts, network errors, 408 and 5xx are outages; 429 and other 4xx are not. */
|
|
331
|
+
export function isProviderOutage(error: unknown): boolean;
|
|
332
|
+
export function isCircuitOpen(error: unknown): boolean;
|
|
333
|
+
|
|
334
|
+
/* ─────────────────── Outbound masking ─────────────────── */
|
|
335
|
+
|
|
336
|
+
export interface DetectedEntity {
|
|
337
|
+
text: string;
|
|
338
|
+
type: string;
|
|
339
|
+
score: number;
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
export interface ReversibleMasker {
|
|
343
|
+
mask(text: string, options?: { names?: string[] }): string;
|
|
344
|
+
/** Runs the detector first (keep it local), learns, then masks. */
|
|
345
|
+
maskAsync(text: string, options?: { names?: string[] }): Promise<string>;
|
|
346
|
+
maskDeep<T>(value: T): T;
|
|
347
|
+
unmask(text: string): string;
|
|
348
|
+
unmaskDeep<T>(value: T): T;
|
|
349
|
+
unmaskStream(chunks: AsyncIterable<unknown>): AsyncGenerator<string>;
|
|
350
|
+
detectNames(text: string): Promise<string[]>;
|
|
351
|
+
size(): number;
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
export function createReversibleMasker(options?: {
|
|
355
|
+
names?: string[];
|
|
356
|
+
patterns?: Array<{ type: string; pattern: RegExp }>;
|
|
357
|
+
detect?: (text: string) => Awaitable<DetectedEntity[] | null | undefined>;
|
|
358
|
+
detectTypes?: string[];
|
|
359
|
+
minScore?: number;
|
|
360
|
+
detectMaxChars?: number;
|
|
361
|
+
minLength?: number;
|
|
362
|
+
token?: (type: string, sequence: number) => string;
|
|
363
|
+
typeOf?: (value: string) => string;
|
|
364
|
+
keep?: (value: string) => boolean;
|
|
365
|
+
}): ReversibleMasker;
|
|
366
|
+
|
|
367
|
+
export function withOutboundMasking<Rest extends unknown[], R>(
|
|
368
|
+
masker: ReversibleMasker,
|
|
369
|
+
call: (input: any, ...rest: Rest) => Awaitable<R>
|
|
370
|
+
): (input: unknown, ...rest: Rest) => Promise<R>;
|
|
371
|
+
|
|
372
|
+
export function headWithoutCuttingWords(text: string, max: number): string;
|
|
373
|
+
|
|
374
|
+
/* ─────────────────── Passages in another language ─────────────────── */
|
|
375
|
+
|
|
376
|
+
export interface Passage {
|
|
377
|
+
title?: string;
|
|
378
|
+
text: string;
|
|
379
|
+
lang?: string;
|
|
380
|
+
kind?: string;
|
|
381
|
+
ref?: unknown;
|
|
382
|
+
url?: string;
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
export interface PassageTexts {
|
|
386
|
+
header?: string;
|
|
387
|
+
footer?: string;
|
|
388
|
+
/** Required when a passage can be foreign. `{languages}` becomes the tags found. */
|
|
389
|
+
foreign?: string;
|
|
390
|
+
empty?: string;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
export function primaryLanguage(tag: unknown): string | null;
|
|
394
|
+
export function isForeignLanguage(passageLanguage: unknown, readerLanguage: unknown): boolean;
|
|
395
|
+
export function markForeignPassages(passages: Passage[], options: { lang: string; tag?: (language: string) => string }): { blocks: string[]; languages: string[] };
|
|
396
|
+
/** `passages: null` means the search failed: nothing is said. */
|
|
397
|
+
export function buildPassagesContext(options: { passages: Passage[] | null | undefined; lang: string; texts?: PassageTexts; tag?: (language: string) => string }): string[];
|
|
398
|
+
export function passageSource(passage: Passage, options?: { excerptMax?: number }): Omit<Passage, 'text'> & { excerpt: string };
|
|
399
|
+
|
|
400
|
+
/* ─────────────────── Sources ─────────────────── */
|
|
401
|
+
|
|
402
|
+
export interface SourceLedger<S = Record<string, unknown>> {
|
|
403
|
+
keep(found: S[], data?: unknown): void;
|
|
404
|
+
sources(): S[];
|
|
405
|
+
evidence(): string[];
|
|
406
|
+
size(): number;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
export function createSourceLedger<S = Record<string, unknown>>(options?: { keyOf?: (source: S) => string }): SourceLedger<S>;
|
|
410
|
+
|
|
411
|
+
export function usedSources<S extends { url?: string; title?: string }, Place = unknown>(
|
|
412
|
+
answer: string,
|
|
413
|
+
sources: S[],
|
|
414
|
+
evidence?: string[],
|
|
415
|
+
options?: {
|
|
416
|
+
references?: (text: string) => Place[];
|
|
417
|
+
sameReference?: (a: Place, b: Place) => boolean;
|
|
418
|
+
ownReference?: (source: S) => Place | null | undefined;
|
|
419
|
+
commonWords?: Iterable<string>;
|
|
420
|
+
minWordLength?: number;
|
|
421
|
+
sharedMin?: number;
|
|
422
|
+
shortEvidence?: number;
|
|
423
|
+
}
|
|
424
|
+
): S[];
|
|
425
|
+
|
|
426
|
+
export interface NliScores { entailment: number; neutral?: number; contradiction: number }
|
|
427
|
+
|
|
428
|
+
export function findContradiction(
|
|
429
|
+
answer: string,
|
|
430
|
+
sources: Array<string | { content?: string; snippet?: string; url?: string; source?: string }>,
|
|
431
|
+
options: {
|
|
432
|
+
compare: (pairs: Array<{ premise: string; hypothesis: string }>) => Awaitable<NliScores[] | null>;
|
|
433
|
+
timeoutMs?: number;
|
|
434
|
+
minWords?: number;
|
|
435
|
+
sharedMin?: number;
|
|
436
|
+
maxPairs?: number;
|
|
437
|
+
contradictionMin?: number;
|
|
438
|
+
entailmentMax?: number;
|
|
439
|
+
commonWords?: Iterable<string>;
|
|
440
|
+
}
|
|
441
|
+
): Promise<{ contradicts: boolean; sentence: string | null; source: string | null } | null>;
|
|
442
|
+
|
|
443
|
+
export function factualSentences(answer: string, minWords: number): string[];
|
|
444
|
+
|
|
445
|
+
export function rerankResults<R, S, F extends { results: R[]; sources?: S[] }>(
|
|
446
|
+
query: string,
|
|
447
|
+
found: F,
|
|
448
|
+
options: {
|
|
449
|
+
score: (query: string, passages: string[]) => Awaitable<number[] | null>;
|
|
450
|
+
passageOf?: (result: R) => string;
|
|
451
|
+
sourceMatches?: (source: S, result: R) => boolean;
|
|
452
|
+
}
|
|
453
|
+
): Promise<F>;
|
|
454
|
+
|
|
455
|
+
/* ─────────────────── Answer text ─────────────────── */
|
|
456
|
+
|
|
457
|
+
export function plainText(text: unknown): string;
|
|
458
|
+
export function tidyMarkdown(text: unknown, options?: { removeEmoji?: boolean }): string;
|
|
459
|
+
export function isFaithfulQuotation(quoted: string, source: string): boolean;
|
|
460
|
+
export function verifyQuotations<Refs = unknown>(text: string, options: {
|
|
461
|
+
findReferences: (text: string) => Awaitable<Array<{ start: number; end: number; refs: Refs }>>;
|
|
462
|
+
resolve: (refs: Refs) => Awaitable<string | null | undefined>;
|
|
463
|
+
}): Promise<string>;
|
|
464
|
+
|
|
465
|
+
/* ─────────────────── Reply language ─────────────────── */
|
|
466
|
+
|
|
467
|
+
export interface LanguageDetector {
|
|
468
|
+
byWords(text: string): string | null;
|
|
469
|
+
reply(text: string, appLanguage: string): Promise<string>;
|
|
470
|
+
languages: string[];
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
export function createLanguageDetector(options: {
|
|
474
|
+
words: Record<string, string[]>;
|
|
475
|
+
identify?: (text: string) => Awaitable<{ language: string; confidence: number }>;
|
|
476
|
+
fallback?: string;
|
|
477
|
+
confidenceMin?: number;
|
|
478
|
+
shortConfidenceMin?: number;
|
|
479
|
+
shortWords?: number;
|
|
480
|
+
lead?: number;
|
|
481
|
+
maxChars?: number;
|
|
482
|
+
}): LanguageDetector;
|
|
483
|
+
|
|
484
|
+
/* ─────────────────── Ask limit ─────────────────── */
|
|
485
|
+
|
|
486
|
+
export interface AskLimitVerdict { allowed: boolean; remaining: number; retryInMs: number }
|
|
487
|
+
|
|
488
|
+
export interface AskLimit {
|
|
489
|
+
/** Throws a 429 AppError with `code` and `retryInMs` past the limit. */
|
|
490
|
+
take(subject: string | number, now?: number): AskLimitVerdict;
|
|
491
|
+
peek(subject: string | number, now?: number): AskLimitVerdict;
|
|
492
|
+
reset(subject?: string | number): void;
|
|
493
|
+
size(): number;
|
|
494
|
+
sweep(now: number): void;
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
export function createAskLimit(options: { max: number; windowMs: number; code?: string; sweepEvery?: number }): AskLimit;
|
|
498
|
+
|
|
499
|
+
/* ─────────────────── OpenAI-compatible endpoints ─────────────────── */
|
|
500
|
+
|
|
501
|
+
export interface ChatMessage {
|
|
502
|
+
role: 'user' | 'assistant' | 'tool' | 'system';
|
|
503
|
+
text?: string;
|
|
504
|
+
content?: string;
|
|
505
|
+
images?: Array<{ mimeType: string; data: string }>;
|
|
506
|
+
toolCalls?: Array<{ id: string; name: string; args: unknown }>;
|
|
507
|
+
toolCallId?: string;
|
|
508
|
+
result?: unknown;
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
export interface ChatToolCall {
|
|
512
|
+
id: string;
|
|
513
|
+
name: string;
|
|
514
|
+
args: Record<string, unknown> | null;
|
|
515
|
+
/** The model sent arguments that are not a JSON object. */
|
|
516
|
+
invalid?: true;
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
export type FetchLike = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; json(): Promise<any> }>;
|
|
520
|
+
|
|
521
|
+
export function askChatModel(
|
|
522
|
+
target: { url: string; key: string; model: string; extra?: Record<string, unknown> },
|
|
523
|
+
request: { system?: string; messages: ChatMessage[]; tools?: Array<Record<string, unknown>>; maxTokens?: number; temperature?: number },
|
|
524
|
+
io: { fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number }
|
|
525
|
+
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
|
|
526
|
+
|
|
527
|
+
export function readToolArguments(raw: unknown): { args: Record<string, unknown> | null; invalid: boolean };
|
|
528
|
+
|
|
529
|
+
export function createOpenAICompatibleProvider(options: {
|
|
530
|
+
id: string;
|
|
531
|
+
url: string;
|
|
532
|
+
getKey: () => Awaitable<string | null | undefined>;
|
|
533
|
+
models: ProviderModel[];
|
|
534
|
+
fetch: FetchLike;
|
|
535
|
+
external?: boolean;
|
|
536
|
+
timeoutMs?: number;
|
|
537
|
+
extra?: Record<string, unknown>;
|
|
538
|
+
toRequest?: (prompt: string, ctx: Record<string, unknown>) => { system?: string; messages: ChatMessage[] };
|
|
539
|
+
}): Provider;
|
package/src/index.js
CHANGED
|
@@ -3,5 +3,15 @@ module.exports = {
|
|
|
3
3
|
...require('./toolRegistry'),
|
|
4
4
|
...require('./agentLoop'),
|
|
5
5
|
...require('./pendingActions'),
|
|
6
|
-
...require('./fallback')
|
|
6
|
+
...require('./fallback'),
|
|
7
|
+
...require('./responseCleaner'),
|
|
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')
|
|
7
17
|
};
|
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 };
|