@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.
@@ -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
  };