@astratra/ai 1.6.0 → 1.8.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/LICENSE +1 -1
- package/README.md +412 -6
- package/guards/package.json +4 -0
- package/guards/testing/package.json +4 -0
- package/package.json +29 -6
- package/src/aiConfig.js +72 -0
- package/src/gemini.js +9 -3
- package/src/guards/createGuards.js +456 -0
- package/src/guards/frame.js +36 -0
- package/src/guards/index.d.ts +150 -0
- package/src/guards/index.js +16 -0
- package/src/guards/leaks.js +63 -0
- package/src/guards/recommended.js +31 -0
- package/src/guards/testing/index.d.ts +30 -0
- package/src/guards/testing/index.js +116 -0
- package/src/index.d.ts +294 -4
- package/src/index.js +9 -1
- package/src/localModels.js +99 -0
- package/src/managedRouter.js +258 -0
- package/src/masking.js +34 -1
- package/src/modelAnswers.js +1 -0
- package/src/nativeTools.js +44 -5
- package/src/openaiCompatible.js +5 -1
- package/src/providerLimits.js +45 -0
- package/src/routingState.js +87 -0
- package/src/serviceHttp.js +56 -0
- package/src/serviceLanguage.js +23 -0
- package/src/voice.js +181 -0
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/* Personal data a reply must not carry unless the person gave it in this run.
|
|
4
|
+
Small on purpose: structured data that can be recognised without a model. */
|
|
5
|
+
|
|
6
|
+
function luhnValid(digits) {
|
|
7
|
+
if (digits.length < 13 || digits.length > 19) return false;
|
|
8
|
+
let sum = 0;
|
|
9
|
+
let double = false;
|
|
10
|
+
for (let i = digits.length - 1; i >= 0; i -= 1) {
|
|
11
|
+
let d = digits.charCodeAt(i) - 48;
|
|
12
|
+
if (double) { d *= 2; if (d > 9) d -= 9; }
|
|
13
|
+
sum += d;
|
|
14
|
+
double = !double;
|
|
15
|
+
}
|
|
16
|
+
return sum % 10 === 0;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function ibanValid(value) {
|
|
20
|
+
const compact = value.replace(/\s/g, '').toUpperCase();
|
|
21
|
+
if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(compact)) return false;
|
|
22
|
+
const moved = compact.slice(4) + compact.slice(0, 4);
|
|
23
|
+
let remainder = 0;
|
|
24
|
+
for (const char of moved) {
|
|
25
|
+
const chunk = /[A-Z]/.test(char) ? String(char.charCodeAt(0) - 55) : char;
|
|
26
|
+
for (const digit of chunk) remainder = (remainder * 10 + (digit.charCodeAt(0) - 48)) % 97;
|
|
27
|
+
}
|
|
28
|
+
return remainder === 1;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const DATE_LIKE = /^\d{4}-\d{2}-\d{2}/;
|
|
32
|
+
|
|
33
|
+
const DETECTORS = [
|
|
34
|
+
{ type: 'email', pattern: () => /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/g, valid: () => true },
|
|
35
|
+
{ type: 'iban', pattern: () => /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{2,5}){3,8}\b/g, valid: ibanValid },
|
|
36
|
+
{ type: 'card', pattern: () => /\b(?:\d[ -]?){13,19}\b/g, valid: (value) => luhnValid(value.replace(/\D/g, '')) },
|
|
37
|
+
{
|
|
38
|
+
type: 'phone',
|
|
39
|
+
pattern: () => /(?<![\w@])\+?\d[\d .()-]{7,17}\d(?![\w@])/g,
|
|
40
|
+
valid: (value) => {
|
|
41
|
+
const digits = value.replace(/\D/g, '');
|
|
42
|
+
return digits.length >= 9 && digits.length <= 15 && !DATE_LIKE.test(value) && !luhnValid(digits);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
];
|
|
46
|
+
|
|
47
|
+
const normal = (type, value) => (type === 'email' ? value.toLowerCase() : value.replace(/[\s.()-]/g, '').toUpperCase());
|
|
48
|
+
|
|
49
|
+
/** Structured personal data in a text: [{ type, value, start, end }] (values stay in memory, never in events). */
|
|
50
|
+
function findPersonalData(text, types) {
|
|
51
|
+
const found = [];
|
|
52
|
+
for (const detector of DETECTORS) {
|
|
53
|
+
if (types && !types.includes(detector.type)) continue;
|
|
54
|
+
for (const match of String(text).matchAll(detector.pattern())) {
|
|
55
|
+
const overlaps = found.some((f) => match.index < f.end && match.index + match[0].length > f.start);
|
|
56
|
+
if (overlaps || !detector.valid(match[0])) continue;
|
|
57
|
+
found.push({ type: detector.type, value: match[0], key: normal(detector.type, match[0]), start: match.index, end: match.index + match[0].length });
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
return found.sort((a, b) => a.start - b.start);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
module.exports = { findPersonalData, luhnValid, ibanValid };
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const { createGuards } = require('./createGuards');
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The preset: every check on, `failClosed` for anything that acts, a lower
|
|
6
|
+
* injection threshold before an action (0.3: flagged content only goes to
|
|
7
|
+
* review) than for plain reading (0.5), personal-data leaks blocked, unsafe
|
|
8
|
+
* replies blocked, unsupported claims flagged. Pass `readOnly: true` for an
|
|
9
|
+
* agent that cannot act: it then fails open when a model of the service is down.
|
|
10
|
+
*
|
|
11
|
+
* @param {object} options { models, onEvent?, names?, readOnly?, verifySources?, policy?, injection?, output? }
|
|
12
|
+
*/
|
|
13
|
+
function recommendedGuards(options = {}) {
|
|
14
|
+
const { readOnly, policy, injection, output, ...rest } = options;
|
|
15
|
+
return createGuards({
|
|
16
|
+
defaultMode: readOnly ? 'read' : 'action',
|
|
17
|
+
...rest,
|
|
18
|
+
policy: {
|
|
19
|
+
failure: { action: 'failClosed', read: readOnly ? 'failOpen' : 'failClosed' },
|
|
20
|
+
onInjection: 'flag',
|
|
21
|
+
onLeak: 'block',
|
|
22
|
+
onModeration: 'block',
|
|
23
|
+
onUnsupported: 'flag',
|
|
24
|
+
...(policy || {})
|
|
25
|
+
},
|
|
26
|
+
injection: { threshold: 0.5, actionThreshold: 0.3, ...(injection || {}) },
|
|
27
|
+
output: { grounding: true, leak: true, moderation: true, minSupport: 0.6, ...(output || {}) }
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
module.exports = { recommendedGuards };
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { CreateGuardsOptions, GuardEvent, GuardModels, Guards } from '../index';
|
|
2
|
+
|
|
3
|
+
export interface FakeModelsRules {
|
|
4
|
+
/** Texts `entities` finds. */
|
|
5
|
+
names?: string[];
|
|
6
|
+
injectionScore?(text: string): number;
|
|
7
|
+
moderate?(text: string): { unsafe: number; categories: Record<string, number> };
|
|
8
|
+
entails?(premise: string, claim: string): boolean;
|
|
9
|
+
/** Endpoints that answer a failure. */
|
|
10
|
+
down?: string[];
|
|
11
|
+
}
|
|
12
|
+
export interface FakeModels extends Required<GuardModels> {
|
|
13
|
+
calls: Array<{ endpoint: string; size: number }>;
|
|
14
|
+
setDown(endpoint: string, down?: boolean): void;
|
|
15
|
+
}
|
|
16
|
+
export function createFakeModels(rules?: FakeModelsRules): FakeModels;
|
|
17
|
+
|
|
18
|
+
export interface EventRecorder {
|
|
19
|
+
(event: GuardEvent): void;
|
|
20
|
+
events: GuardEvent[];
|
|
21
|
+
last(): GuardEvent | undefined;
|
|
22
|
+
decisions(guard?: string): string[];
|
|
23
|
+
}
|
|
24
|
+
export function createEventRecorder(): EventRecorder;
|
|
25
|
+
export function createMockGuards(options?: Omit<CreateGuardsOptions, 'models'> & { rules?: FakeModelsRules; models?: GuardModels }): {
|
|
26
|
+
guards: Guards;
|
|
27
|
+
models: GuardModels;
|
|
28
|
+
events: GuardEvent[];
|
|
29
|
+
recorder: EventRecorder;
|
|
30
|
+
};
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const { createGuards } = require('../createGuards');
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Light stand-ins for tests: no model, no network, no service.
|
|
6
|
+
*
|
|
7
|
+
* createFakeModels(rules) a client shaped like @astratra/models' (entities, injection,
|
|
8
|
+
* moderation, nli) answering from simple rules you can override
|
|
9
|
+
* createMockGuards(options) the real guards over that fake client, plus an event recorder
|
|
10
|
+
* createEventRecorder() collects the events the guards emit
|
|
11
|
+
*
|
|
12
|
+
* The fakes are keyword rules, not detectors: they exist so the code around the guards
|
|
13
|
+
* (an agent loop, a route) can be tested for what it does with a decision.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const INJECTION_WORDS = /ignore (all )?(the )?(previous|prior|above) (instructions|rules)|ignore(z)? (toutes )?(les )?(instructions|consignes) pr[ée]c[ée]dentes|system prompt|invite syst[èe]me/i;
|
|
17
|
+
const UNSAFE_WORDS = /\b(kill you|je vais te tuer|suicide|suicider)\b/i;
|
|
18
|
+
|
|
19
|
+
const ok = (data) => ({ ok: true, ...data });
|
|
20
|
+
const fail = (endpoint, code = 'unavailable') => ({ ok: false, code, endpoint, retryable: true });
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* @param {object} [rules] each optional:
|
|
24
|
+
* names: string[] texts `entities` finds (default: none)
|
|
25
|
+
* injectionScore(text) 0..1 (default: 0.97 on a classic override phrase, else 0.01)
|
|
26
|
+
* moderate(text) { unsafe, categories } (default: flagged on a few violent words)
|
|
27
|
+
* entails(premise, claim) boolean (default: every word of the claim appears in the premise)
|
|
28
|
+
* down: string[] endpoints that answer a failure, e.g. ['injection']
|
|
29
|
+
*/
|
|
30
|
+
function createFakeModels(rules = {}) {
|
|
31
|
+
const down = new Set(rules.down || []);
|
|
32
|
+
const calls = [];
|
|
33
|
+
const score = rules.injectionScore || ((text) => (INJECTION_WORDS.test(text) ? 0.97 : 0.01));
|
|
34
|
+
const moderate = rules.moderate || ((text) => (UNSAFE_WORDS.test(text) ? { unsafe: 0.95, categories: { violence: 0.9 } } : { unsafe: 0.01, categories: {} }));
|
|
35
|
+
const words = (t) => new Set(String(t).toLowerCase().match(/[\p{L}\p{N}]+/gu) || []);
|
|
36
|
+
const entails = rules.entails || ((premise, claim) => {
|
|
37
|
+
const have = words(premise);
|
|
38
|
+
return [...words(claim)].every((w) => have.has(w));
|
|
39
|
+
});
|
|
40
|
+
const wrap = (endpoint, run) => async (...args) => {
|
|
41
|
+
calls.push({ endpoint, size: Array.isArray(args[0]) ? args[0].length : 1 });
|
|
42
|
+
if (down.has(endpoint)) return fail(endpoint);
|
|
43
|
+
return run(...args);
|
|
44
|
+
};
|
|
45
|
+
const list = (input) => (typeof input === 'string' ? [input] : input);
|
|
46
|
+
return {
|
|
47
|
+
calls,
|
|
48
|
+
setDown: (endpoint, isDown = true) => (isDown ? down.add(endpoint) : down.delete(endpoint)),
|
|
49
|
+
entities: wrap('entities', (text) => ok({
|
|
50
|
+
entities: (rules.names || []).flatMap((name) => {
|
|
51
|
+
const start = text.indexOf(name);
|
|
52
|
+
return start < 0 ? [] : [{ text: name, label: 'person', start, end: start + name.length, score: 0.95 }];
|
|
53
|
+
}),
|
|
54
|
+
model: 'fake-entities'
|
|
55
|
+
})),
|
|
56
|
+
injection: wrap('injection', (input) => {
|
|
57
|
+
const results = list(input).map((text) => { const s = score(text); return { score: s, verdict: s >= 0.5 ? 'injection' : 'safe' }; });
|
|
58
|
+
return ok({ results, threshold: 0.5, model: 'fake-injection' });
|
|
59
|
+
}),
|
|
60
|
+
moderation: wrap('moderation', (input) => {
|
|
61
|
+
const results = list(input).map((text) => {
|
|
62
|
+
const r = moderate(text);
|
|
63
|
+
return { flagged: r.unsafe >= 0.5, unsafe: r.unsafe, categories: r.categories, flaggedCategories: r.unsafe >= 0.5 ? Object.keys(r.categories) : [] };
|
|
64
|
+
});
|
|
65
|
+
return ok({ results, model: 'fake-moderation' });
|
|
66
|
+
}),
|
|
67
|
+
nli: wrap('nli', (pairs) => ok({
|
|
68
|
+
results: pairs.map((p) => (entails(p.premise, p.hypothesis)
|
|
69
|
+
? { entailment: 0.95, neutral: 0.04, contradiction: 0.01 }
|
|
70
|
+
: { entailment: 0.05, neutral: 0.9, contradiction: 0.05 })),
|
|
71
|
+
model: 'fake-nli'
|
|
72
|
+
}))
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function createEventRecorder() {
|
|
77
|
+
const events = [];
|
|
78
|
+
const record = (event) => { events.push(event); };
|
|
79
|
+
record.events = events;
|
|
80
|
+
record.last = () => events[events.length - 1];
|
|
81
|
+
record.decisions = (guard) => events.filter((e) => !guard || e.guard === guard).map((e) => e.decision);
|
|
82
|
+
return record;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* The real guards over a fake models client. Returns `{ guards, models, events }`.
|
|
87
|
+
* @param {object} [options] { rules (see createFakeModels), models, ...createGuards options }
|
|
88
|
+
*/
|
|
89
|
+
function createMockGuards(options = {}) {
|
|
90
|
+
const { rules, models, ...rest } = options;
|
|
91
|
+
const fake = models || createFakeModels(rules);
|
|
92
|
+
const events = createEventRecorder();
|
|
93
|
+
const guards = createGuards({
|
|
94
|
+
onEvent: (event) => { events(event); if (rest.onEvent) rest.onEvent(event); },
|
|
95
|
+
...rest,
|
|
96
|
+
models: fake,
|
|
97
|
+
verifySources: rest.verifySources || simpleVerifySources
|
|
98
|
+
});
|
|
99
|
+
return { guards, models: fake, events: events.events, recorder: events };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/* The same contract as verifySources of @astratra/rag, minimal: one claim per sentence,
|
|
103
|
+
checked against every source. Keeps the testing entry point free of other packages. */
|
|
104
|
+
async function simpleVerifySources(answer, sources, { nli }) {
|
|
105
|
+
const claims = String(answer).split(/(?<=[.!?])\s+|\n+/).map((c) => c.trim()).filter((c) => c && !/\?$/.test(c));
|
|
106
|
+
const claimsOut = [];
|
|
107
|
+
for (const claim of claims) {
|
|
108
|
+
const pairs = sources.map((premise) => ({ premise, hypothesis: claim }));
|
|
109
|
+
const scores = pairs.length ? await nli(pairs) : [];
|
|
110
|
+
const best = Math.max(0, ...scores.map((s) => s.entailment));
|
|
111
|
+
claimsOut.push({ category: best >= 0.5 ? 'SUPPORTED' : 'UNSUPPORTED', claim, source: null });
|
|
112
|
+
}
|
|
113
|
+
return { code: 'OK', claims: claimsOut, flags: [] };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
module.exports = { createFakeModels, createMockGuards, createEventRecorder };
|
package/src/index.d.ts
CHANGED
|
@@ -422,6 +422,10 @@ export interface ReversibleMasker {
|
|
|
422
422
|
unmaskStream(chunks: AsyncIterable<unknown>): AsyncGenerator<string>;
|
|
423
423
|
detectNames(text: string): Promise<string[]>;
|
|
424
424
|
size(): number;
|
|
425
|
+
/** The table as JSON (it holds the real values: store it like the data it protects). */
|
|
426
|
+
snapshot(): unknown;
|
|
427
|
+
/** Put a table from `snapshot()` back, replacing what was known. */
|
|
428
|
+
restore(snapshot: unknown): void;
|
|
425
429
|
}
|
|
426
430
|
|
|
427
431
|
export function createReversibleMasker(options?: {
|
|
@@ -602,7 +606,7 @@ export function askChatModel(
|
|
|
602
606
|
target: { url: string; key: string; model: string; extra?: Record<string, unknown> },
|
|
603
607
|
request: { system?: string; messages: ChatMessage[]; tools?: Array<Record<string, unknown>>; maxTokens?: number; temperature?: number },
|
|
604
608
|
io: { fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number }
|
|
605
|
-
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
|
|
609
|
+
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean; retryAfterMs?: number }>;
|
|
606
610
|
|
|
607
611
|
export function readToolArguments(raw: unknown): { args: Record<string, unknown> | null; invalid: boolean; reason?: 'not_json' | 'not_object'; detail?: string };
|
|
608
612
|
|
|
@@ -650,12 +654,14 @@ export function createOpenAICompatibleProvider(options: ChatProviderOptions & {
|
|
|
650
654
|
export function askGeminiModel(
|
|
651
655
|
model: string,
|
|
652
656
|
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 }>;
|
|
657
|
+
io: { key: string; fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number; endpoint?: string; noSystemInstruction?: (model: string) => boolean; extra?: Record<string, unknown> }
|
|
658
|
+
): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean; retryAfterMs?: number }>;
|
|
655
659
|
|
|
656
660
|
export function createGeminiProvider(options: ChatProviderOptions & {
|
|
657
661
|
id?: string;
|
|
658
662
|
endpoint?: string;
|
|
663
|
+
external?: boolean;
|
|
664
|
+
extra?: Record<string, unknown>;
|
|
659
665
|
/** Défaut : les modèles Gemma, qui ne prennent pas de consigne système. */
|
|
660
666
|
noSystemInstruction?: (model: string) => boolean;
|
|
661
667
|
}): Provider;
|
|
@@ -677,6 +683,7 @@ export interface NativeTool<Ctx = Record<string, unknown>> {
|
|
|
677
683
|
description: string;
|
|
678
684
|
parameters: { type: 'object'; [key: string]: unknown };
|
|
679
685
|
kind: NativeToolKind;
|
|
686
|
+
risk?: DeclaredToolRisk;
|
|
680
687
|
summary?: (args: Record<string, unknown>) => Record<string, string | number>;
|
|
681
688
|
run(args: Record<string, unknown>, ctx: Ctx & { signal: AbortSignal }): Awaitable<NativeToolResult | null | undefined>;
|
|
682
689
|
perform?(args: Record<string, unknown>, ctx: Ctx): Awaitable<NativeToolResult | null | undefined>;
|
|
@@ -684,7 +691,7 @@ export interface NativeTool<Ctx = Record<string, unknown>> {
|
|
|
684
691
|
}
|
|
685
692
|
|
|
686
693
|
export const NATIVE_TOOL_KINDS: string[];
|
|
687
|
-
export function validateNativeTools<T extends NativeTool<any>>(tools: T[], options?: { kinds?: string[]; requireSummary?: boolean }): T[];
|
|
694
|
+
export function validateNativeTools<T extends NativeTool<any>>(tools: T[], options?: { kinds?: string[]; requireSummary?: boolean; requireRisk?: boolean }): T[];
|
|
688
695
|
export function toolSpecs(tools: NativeTool<any>[]): Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
|
|
689
696
|
export function stepParams(tool: NativeTool<any> | null | undefined, args: unknown, options?: { max?: number }): Record<string, string | number>;
|
|
690
697
|
|
|
@@ -707,6 +714,9 @@ export interface ToolMessage {
|
|
|
707
714
|
export function createToolCaller<Ctx = Record<string, unknown>>(options: {
|
|
708
715
|
tools: Map<string, NativeTool<Ctx>> | NativeTool<Ctx>[];
|
|
709
716
|
context?: Ctx;
|
|
717
|
+
confirmationPolicy?: 'always' | 'never' | { threshold: ToolRisk };
|
|
718
|
+
exposure?: { untrusted: boolean };
|
|
719
|
+
readsUntrusted?: (tool: NativeTool<Ctx>, found: NativeToolResult | null | undefined) => boolean;
|
|
710
720
|
signal?: AbortSignal;
|
|
711
721
|
timeoutMs?: number;
|
|
712
722
|
now?: () => number;
|
|
@@ -817,3 +827,283 @@ export function createLlamaCppProvider(options?: LlamaCppConfigInput & {
|
|
|
817
827
|
fetch?: (url: string, init: object) => Awaitable<Response>;
|
|
818
828
|
sleep?: (ms: number) => Promise<void>;
|
|
819
829
|
}): LlamaCppProvider;
|
|
830
|
+
|
|
831
|
+
/* Configured routing, local model services and voice. */
|
|
832
|
+
export type AiUsage = 'quick' | 'chat' | 'tools' | 'pilot' | 'json' | 'vision';
|
|
833
|
+
export interface RoutingState {
|
|
834
|
+
day: string;
|
|
835
|
+
rpmWindow: number[];
|
|
836
|
+
rpdUsed: number;
|
|
837
|
+
tpdUsed: number;
|
|
838
|
+
cooldownUntil: number;
|
|
839
|
+
degradedUntil: number;
|
|
840
|
+
failures: number;
|
|
841
|
+
disabled: boolean;
|
|
842
|
+
}
|
|
843
|
+
/** update must be atomic across all users of the store. The callback is synchronous
|
|
844
|
+
* and side-effect free: a CAS adapter may call it more than once. */
|
|
845
|
+
export interface RoutingStateStore {
|
|
846
|
+
read(key: string): Awaitable<RoutingState | null>;
|
|
847
|
+
update<T>(key: string, change: (state: RoutingState | null) => { state: RoutingState | null; value?: T }): Awaitable<T | undefined>;
|
|
848
|
+
}
|
|
849
|
+
export function createMemoryRoutingStore(): RoutingStateStore;
|
|
850
|
+
export interface RoutingRedisClient {
|
|
851
|
+
get(key: string): Promise<string | null>;
|
|
852
|
+
eval(script: string, options: { keys: string[]; arguments: string[] }): Promise<unknown>;
|
|
853
|
+
}
|
|
854
|
+
export function createRedisRoutingStore(options: { client: RoutingRedisClient; prefix?: string; ttlMs?: number; maxRetries?: number }): RoutingStateStore;
|
|
855
|
+
export interface RoutingPgConnection {
|
|
856
|
+
query(sql: string, params?: unknown[]): Promise<{ rows: Array<{ state?: RoutingState }> }>;
|
|
857
|
+
release(): void;
|
|
858
|
+
}
|
|
859
|
+
export interface RoutingPgPool {
|
|
860
|
+
query(sql: string, params?: unknown[]): Promise<{ rows: Array<{ state?: RoutingState }> }>;
|
|
861
|
+
connect(): Promise<RoutingPgConnection>;
|
|
862
|
+
}
|
|
863
|
+
export function createPostgresRoutingStore(options: { pool: RoutingPgPool; table?: string }): RoutingStateStore & { initialize(): Promise<void> };
|
|
864
|
+
export type AiKeys = string[] | string | ((ctx: Record<string, unknown>) => Awaitable<string[] | string | null | undefined>);
|
|
865
|
+
export interface ConfiguredProviderModel extends ProviderModel {
|
|
866
|
+
vision?: boolean;
|
|
867
|
+
visionOnly?: boolean;
|
|
868
|
+
extra?: Record<string, unknown>;
|
|
869
|
+
maxTokens?: number;
|
|
870
|
+
disabled?: boolean;
|
|
871
|
+
preview?: boolean;
|
|
872
|
+
languages?: string[];
|
|
873
|
+
noAnalytics?: boolean;
|
|
874
|
+
maxInputTokens?: number;
|
|
875
|
+
}
|
|
876
|
+
export interface ConfiguredProvider {
|
|
877
|
+
id: string;
|
|
878
|
+
format: 'openai' | 'gemini';
|
|
879
|
+
/** Full OpenAI chat URL, or Gemini models endpoint (without the model). */
|
|
880
|
+
url: string;
|
|
881
|
+
keys?: AiKeys;
|
|
882
|
+
keysByUsage?: Record<string, AiKeys>;
|
|
883
|
+
keyLane?: (ctx: Record<string, unknown>) => string | null | undefined;
|
|
884
|
+
/** False by default. Local providers work without API credentials. */
|
|
885
|
+
local?: boolean;
|
|
886
|
+
vision?: boolean;
|
|
887
|
+
extra?: Record<string, unknown>;
|
|
888
|
+
models: ConfiguredProviderModel[];
|
|
889
|
+
/** Share model quotas between credentials when they belong to one account. */
|
|
890
|
+
sharedKeyQuotas?: boolean;
|
|
891
|
+
maxConcurrent?: number;
|
|
892
|
+
maxQueue?: number;
|
|
893
|
+
/** Provider variable stem used by readAiConfigFromEnv. */
|
|
894
|
+
envName?: string;
|
|
895
|
+
}
|
|
896
|
+
export interface ConfiguredRouterConfig {
|
|
897
|
+
cooldownJitterMs?: number;
|
|
898
|
+
providers?: ConfiguredProvider[];
|
|
899
|
+
usages?: Partial<Record<AiUsage, RouteCandidate[]>>;
|
|
900
|
+
intentRouting?: Record<string, { preferred: string[] }>;
|
|
901
|
+
store?: RoutingStateStore;
|
|
902
|
+
statePrefix?: string;
|
|
903
|
+
fetch?: FetchLike;
|
|
904
|
+
now?: () => number;
|
|
905
|
+
quotaMargin?: number | { rpm?: number; rpd?: number; tpd?: number };
|
|
906
|
+
tokenBuffer?: number;
|
|
907
|
+
cooldownMs?: number;
|
|
908
|
+
degradedMs?: number;
|
|
909
|
+
maxFailures?: number;
|
|
910
|
+
waitedTimeoutMs?: number;
|
|
911
|
+
backgroundTimeoutMs?: number;
|
|
912
|
+
whenAllCooling?: 'skip' | 'try';
|
|
913
|
+
reserveVision?: boolean;
|
|
914
|
+
}
|
|
915
|
+
export interface ConfiguredRouteOptions {
|
|
916
|
+
usage?: AiUsage;
|
|
917
|
+
complexity?: string;
|
|
918
|
+
intent?: string;
|
|
919
|
+
candidates?: RouteCandidate[];
|
|
920
|
+
exclude?: string[];
|
|
921
|
+
language?: string;
|
|
922
|
+
hasAnalytics?: boolean;
|
|
923
|
+
estimatedTokens?: number;
|
|
924
|
+
purpose?: string;
|
|
925
|
+
waitedOn?: boolean;
|
|
926
|
+
timeoutMs?: number;
|
|
927
|
+
signal?: AbortSignal;
|
|
928
|
+
context?: Record<string, unknown>;
|
|
929
|
+
json?: boolean;
|
|
930
|
+
fallbackWithoutTools?: boolean;
|
|
931
|
+
accepts?: (answer: DetailedAnswer) => boolean;
|
|
932
|
+
}
|
|
933
|
+
export interface ConfiguredRouteResult extends RouteResult<DetailedAnswer> {
|
|
934
|
+
stateKey: string;
|
|
935
|
+
usage: AiUsage;
|
|
936
|
+
complexity: string;
|
|
937
|
+
fallback: boolean;
|
|
938
|
+
}
|
|
939
|
+
export interface ConfiguredRouter {
|
|
940
|
+
route(input: ChatRequest | string, options?: ConfiguredRouteOptions, context?: Record<string, unknown>): Promise<ConfiguredRouteResult>;
|
|
941
|
+
ask(input: ChatRequest | string, options?: ConfiguredRouteOptions, context?: Record<string, unknown>): Promise<DetailedAnswer>;
|
|
942
|
+
getStats(): Promise<Record<string, RoutingState>>;
|
|
943
|
+
/** Resets only state keys seen by this instance. */
|
|
944
|
+
reset(): Promise<void>;
|
|
945
|
+
stop(): void;
|
|
946
|
+
store: RoutingStateStore;
|
|
947
|
+
}
|
|
948
|
+
export function createConfiguredRouter(config?: ConfiguredRouterConfig): ConfiguredRouter;
|
|
949
|
+
export function estimateRequestComplexity(input: ChatRequest | string): 'simple' | 'medium' | 'complex';
|
|
950
|
+
export function estimateRequestTokens(request: ChatRequest): number;
|
|
951
|
+
export function readEnvironmentKeys(env: Record<string, string | undefined>, name: string): string[];
|
|
952
|
+
export interface AiEnvironmentConfig extends ConfiguredRouterConfig {
|
|
953
|
+
localModels: LocalModelsOptions;
|
|
954
|
+
language: ServiceLanguageOptions;
|
|
955
|
+
voice: SpeechServiceOptions & TranscriptionServiceOptions;
|
|
956
|
+
}
|
|
957
|
+
export function readAiConfigFromEnv(options?: { env?: Record<string, string | undefined>; prefix?: string }): AiEnvironmentConfig;
|
|
958
|
+
|
|
959
|
+
export class AiServiceError extends Error {
|
|
960
|
+
constructor(code: string, status?: number | null);
|
|
961
|
+
code: string;
|
|
962
|
+
status: number | null;
|
|
963
|
+
statusCode: number | null;
|
|
964
|
+
}
|
|
965
|
+
export type ServiceFetch = (url: string, init: RequestInit) => Promise<Pick<Response, 'ok' | 'status' | 'json' | 'arrayBuffer'>>;
|
|
966
|
+
export function createTokenFileReader(options?: {
|
|
967
|
+
tokenFile?: string;
|
|
968
|
+
read?: (path: string, encoding: 'utf8') => Promise<string>;
|
|
969
|
+
now?: () => number;
|
|
970
|
+
refreshMs?: number;
|
|
971
|
+
}): () => Promise<string | null>;
|
|
972
|
+
export interface ServiceRequestOptions {
|
|
973
|
+
fetch?: ServiceFetch;
|
|
974
|
+
timeoutMs?: number;
|
|
975
|
+
signal?: AbortSignal;
|
|
976
|
+
headers?: Record<string, string>;
|
|
977
|
+
body?: unknown;
|
|
978
|
+
rawBody?: BodyInit;
|
|
979
|
+
read?: 'json' | 'bytes';
|
|
980
|
+
}
|
|
981
|
+
export function serviceRequest(url: string | null | undefined, options?: ServiceRequestOptions & { read?: 'json' }): Promise<any>;
|
|
982
|
+
export function serviceRequest(url: string | null | undefined, options: ServiceRequestOptions & { read: 'bytes' }): Promise<Buffer>;
|
|
983
|
+
export function endpoint(base: string | null | undefined, path: string): string | null;
|
|
984
|
+
export const LOCAL_VECTOR_MODEL: string;
|
|
985
|
+
export const LOCAL_VECTOR_DIMENSIONS: number;
|
|
986
|
+
export function validPcmAudio(audio: unknown): boolean;
|
|
987
|
+
export interface LocalModelsOptions {
|
|
988
|
+
baseUrl?: string;
|
|
989
|
+
tokenFile?: string;
|
|
990
|
+
readTokenFile?: (path: string, encoding: 'utf8') => Promise<string>;
|
|
991
|
+
tokenRefreshMs?: number;
|
|
992
|
+
timeoutMs?: number;
|
|
993
|
+
maxFailures?: number;
|
|
994
|
+
cooldownMs?: number;
|
|
995
|
+
now?: () => number;
|
|
996
|
+
fetch?: ServiceFetch;
|
|
997
|
+
vectorModel?: string;
|
|
998
|
+
vectorDimensions?: number;
|
|
999
|
+
onError?: (error: AiServiceError, route: string) => void;
|
|
1000
|
+
}
|
|
1001
|
+
export interface LocalCallOptions { timeoutMs?: number; signal?: AbortSignal }
|
|
1002
|
+
export interface NliPair { premisse: string; hypothese: string }
|
|
1003
|
+
export interface NliResult { accord: number; neutre: number; contradiction: number }
|
|
1004
|
+
export interface LocalEntity { texte: string; type: string; debut: number; fin: number; score: number }
|
|
1005
|
+
export type LocalVectors = number[][] & { readonly modele: string; readonly dimensions: number };
|
|
1006
|
+
export interface LocalTranscription { texte: string; langue: string; logprob: number; sansParole: number; dureeMs: number }
|
|
1007
|
+
export interface LocalModelsClient {
|
|
1008
|
+
rerank(question: string, passages: string[], options?: LocalCallOptions): Promise<number[] | null>;
|
|
1009
|
+
compare(pairs: Array<{ premise: string; hypothesis: string }>, options?: LocalCallOptions): Promise<Array<{ entailment: number; neutral: number; contradiction: number }> | null>;
|
|
1010
|
+
entities(text: string, labels: string[], options?: LocalCallOptions): Promise<Array<{ text: string; type: string; start: number; end: number; score: number }> | null>;
|
|
1011
|
+
embed(texts: string[], options?: LocalCallOptions): Promise<LocalVectors | null>;
|
|
1012
|
+
reclasser(question: string, passages: string[], options?: LocalCallOptions): Promise<number[] | null>;
|
|
1013
|
+
nli(pairs: NliPair[], options?: LocalCallOptions): Promise<NliResult[] | null>;
|
|
1014
|
+
comparer(pairs: NliPair[], options?: LocalCallOptions): Promise<NliResult[] | null>;
|
|
1015
|
+
entites(text: string, labels: string[], options?: LocalCallOptions): Promise<LocalEntity[] | null>;
|
|
1016
|
+
vecteurs(texts: string[], options?: LocalCallOptions): Promise<LocalVectors | null>;
|
|
1017
|
+
transcrire(audio: string, options?: LocalCallOptions & { langue?: string; vocabulaire?: string }): Promise<LocalTranscription | null>;
|
|
1018
|
+
disponible(route: string): boolean;
|
|
1019
|
+
available(route: string): boolean;
|
|
1020
|
+
}
|
|
1021
|
+
export function createLocalModelsClient(options?: LocalModelsOptions): LocalModelsClient;
|
|
1022
|
+
export const DEFAULT_LANGUAGE_WORDS: Readonly<Record<string, string[]>>;
|
|
1023
|
+
export interface ServiceLanguageOptions extends Omit<Parameters<typeof createLanguageDetector>[0], 'words' | 'identify'> {
|
|
1024
|
+
words?: Record<string, string[]>;
|
|
1025
|
+
baseUrl?: string;
|
|
1026
|
+
fetch?: ServiceFetch;
|
|
1027
|
+
timeoutMs?: number;
|
|
1028
|
+
}
|
|
1029
|
+
export function createServiceLanguageDetector(options?: ServiceLanguageOptions): LanguageDetector;
|
|
1030
|
+
|
|
1031
|
+
export interface VoiceProviderOptions {
|
|
1032
|
+
keys?: string[] | string | (() => Awaitable<string[] | string | undefined | null>);
|
|
1033
|
+
models?: string[];
|
|
1034
|
+
timeoutMs?: number;
|
|
1035
|
+
cooldownMs?: number;
|
|
1036
|
+
}
|
|
1037
|
+
export interface TranscriptionServiceOptions {
|
|
1038
|
+
local?: Pick<LocalModelsClient, 'transcrire'>;
|
|
1039
|
+
localModels?: LocalModelsOptions;
|
|
1040
|
+
localTimeoutMs?: number;
|
|
1041
|
+
groq?: VoiceProviderOptions & { url?: string };
|
|
1042
|
+
cloudflare?: VoiceProviderOptions & { url?: string | ((model: string) => string) };
|
|
1043
|
+
fetch?: ServiceFetch;
|
|
1044
|
+
now?: () => number;
|
|
1045
|
+
maxAudioBytes?: number;
|
|
1046
|
+
noSpeechThreshold?: number;
|
|
1047
|
+
logprobThreshold?: number;
|
|
1048
|
+
stockPhrases?: readonly string[];
|
|
1049
|
+
}
|
|
1050
|
+
export interface TranscriptionInput {
|
|
1051
|
+
/** PCM16 little-endian, 16kHz mono by default; base64 or bytes. */
|
|
1052
|
+
audio: string | Uint8Array;
|
|
1053
|
+
format?: 'pcm16' | 'wav' | 'file';
|
|
1054
|
+
language?: string;
|
|
1055
|
+
vocabulary?: string;
|
|
1056
|
+
filename?: string;
|
|
1057
|
+
mimeType?: string;
|
|
1058
|
+
signal?: AbortSignal;
|
|
1059
|
+
allowRemote?: boolean;
|
|
1060
|
+
}
|
|
1061
|
+
export interface TranscriptionResult {
|
|
1062
|
+
text: string;
|
|
1063
|
+
language: string | null;
|
|
1064
|
+
provider: 'local' | 'groq' | 'cloudflare';
|
|
1065
|
+
model: string;
|
|
1066
|
+
fallback: boolean;
|
|
1067
|
+
confidence?: number;
|
|
1068
|
+
noSpeech?: boolean;
|
|
1069
|
+
}
|
|
1070
|
+
export function createTranscriptionService(options?: TranscriptionServiceOptions): { transcribe(input: TranscriptionInput): Promise<TranscriptionResult> };
|
|
1071
|
+
export interface SpeechServiceOptions {
|
|
1072
|
+
/** Synthesis order. Default: Gemini (online) first, Piper (local) as fallback. */
|
|
1073
|
+
order?: Array<'gemini' | 'piper'>;
|
|
1074
|
+
piper?: {
|
|
1075
|
+
baseUrl?: string;
|
|
1076
|
+
tokenFile?: string;
|
|
1077
|
+
readTokenFile?: (path: string, encoding: 'utf8') => Promise<string>;
|
|
1078
|
+
timeoutMs?: number;
|
|
1079
|
+
cooldownMs?: number;
|
|
1080
|
+
};
|
|
1081
|
+
gemini?: VoiceProviderOptions & { endpoint?: string; voice?: string };
|
|
1082
|
+
now?: () => number;
|
|
1083
|
+
fetch?: ServiceFetch;
|
|
1084
|
+
prepareText?: (text: string) => string;
|
|
1085
|
+
}
|
|
1086
|
+
export interface SpeechResult {
|
|
1087
|
+
audio: Buffer;
|
|
1088
|
+
format: 'wav';
|
|
1089
|
+
mimeType: 'audio/wav';
|
|
1090
|
+
sampleRate: number;
|
|
1091
|
+
channels: number;
|
|
1092
|
+
provider: 'piper' | 'gemini';
|
|
1093
|
+
model: string | null;
|
|
1094
|
+
fallback: boolean;
|
|
1095
|
+
}
|
|
1096
|
+
export function createSpeechService(options?: SpeechServiceOptions): { synthesize(input: { text: string; language?: string; signal?: AbortSignal; allowRemote?: boolean }): Promise<SpeechResult> };
|
|
1097
|
+
export function pcmToWav(pcm: Uint8Array, options?: { sampleRate?: number; channels?: number }): Buffer;
|
|
1098
|
+
export function readPcmWav(audio: Uint8Array): { pcm: Buffer; sampleRate: number; channels: number };
|
|
1099
|
+
export function speakableText(text: string, maxChars?: number): string;
|
|
1100
|
+
export function doubtfulTranscription(text: string, options?: { stockPhrases?: readonly string[] }): boolean;
|
|
1101
|
+
export const WHISPER_STOCK_PHRASES: readonly string[];
|
|
1102
|
+
export function toolRiskOf(tool: { risk?: string } | null | undefined): ToolRisk;
|
|
1103
|
+
export function waitsForToolConfirmation(tool: { risk?: string; kind?: string } | null | undefined, options?: { policy?: 'always' | 'never' | { threshold: ToolRisk }; untrusted?: boolean }): boolean;
|
|
1104
|
+
|
|
1105
|
+
export function readRetryAfter(response: { headers?: { get(name: string): string | null } }, now?: number): number | null;
|
|
1106
|
+
export function createInferenceQueue(options?: { maxConcurrent?: number; maxQueue?: number }): {
|
|
1107
|
+
run<T>(task: () => Awaitable<T>, options?: { signal?: AbortSignal }): Promise<T>;
|
|
1108
|
+
stats(): { active: number; waiting: number };
|
|
1109
|
+
};
|
package/src/index.js
CHANGED
|
@@ -18,5 +18,13 @@ module.exports = {
|
|
|
18
18
|
...require('./gemini'),
|
|
19
19
|
...require('./nativeTools'),
|
|
20
20
|
...require('./eventStream'),
|
|
21
|
-
...require('./webSearch')
|
|
21
|
+
...require('./webSearch'),
|
|
22
|
+
...require('./managedRouter'),
|
|
23
|
+
...require('./routingState'),
|
|
24
|
+
...require('./aiConfig'),
|
|
25
|
+
...require('./localModels'),
|
|
26
|
+
...require('./serviceHttp'),
|
|
27
|
+
...require('./serviceLanguage'),
|
|
28
|
+
...require('./voice'),
|
|
29
|
+
...require('./providerLimits')
|
|
22
30
|
};
|