@astratra/ai 1.5.0 → 1.7.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/src/index.d.ts CHANGED
@@ -118,12 +118,19 @@ export interface ToolDefinition<TParams = Record<string, unknown>, TResult = unk
118
118
  roles: string[];
119
119
  /** Reaches outside (web search, third-party API): its parameters are masked. */
120
120
  external?: boolean;
121
+ /** Niveau de risque déclaré ; absent, le registre utilise UNKNOWN. */
122
+ risk?: DeclaredToolRisk;
121
123
  params?: Record<string, unknown>;
122
124
  handler(params: TParams, ctx: Record<string, unknown>): Awaitable<TResult>;
123
125
  }
124
126
 
125
- export interface RegisteredTool<TParams = Record<string, unknown>, TResult = unknown> extends ToolDefinition<TParams, TResult> {
127
+ export type ToolRisk = 'LOW' | 'MEDIUM' | 'HIGH' | 'UNKNOWN';
128
+ export type DeclaredToolRisk = Exclude<ToolRisk, 'UNKNOWN'>;
129
+ export const TOOL_RISKS: Readonly<Record<ToolRisk, number>>;
130
+
131
+ export interface RegisteredTool<TParams = Record<string, unknown>, TResult = unknown> extends Omit<ToolDefinition<TParams, TResult>, 'risk'> {
126
132
  params: Record<string, unknown>;
133
+ risk: ToolRisk;
127
134
  }
128
135
 
129
136
  export interface ToolRegistry {
@@ -183,9 +190,28 @@ export interface AgentLoopOptions {
183
190
  maxMs?: number;
184
191
  /** When steps or time run out: one last turn without tools, with this instruction. */
185
192
  finalInstruction?: string;
193
+ /** Seuils d'appels strictement identiques (défauts : 3, 5 et 8). */
194
+ loopGuard?: { reminder?: number; firmReminder?: number; stop?: number };
195
+ /** Mise de côté au-delà du seuil en caractères (défaut : 12 000). */
196
+ spill?: { threshold?: number; store?: SpillStore };
197
+ /** Politique active uniquement lorsqu'elle est fournie : always, never ou seuil de risque. */
198
+ confirmationPolicy?: 'always' | 'never' | { threshold: ToolRisk };
199
+ /** Analyseurs supplémentaires ; le risque le plus élevé prévaut. */
200
+ riskAnalyzers?: Array<(toolCall: ToolCall, ctx: Record<string, unknown>, tool: RegisteredTool) => Awaitable<ToolRisk>>;
201
+ /** Adaptateur de createPendingActions ; les actions créées attendent leur approbation. */
202
+ pendingActions?: Pick<PendingActions, 'propose'>;
203
+ onEvent?: (event: { type: 'tool_loop_warning' | 'tool_loop_stopped'; name: string; repetitions: number; message?: string; reason?: string }) => void;
186
204
  now?: () => number;
187
205
  }
188
206
 
207
+ export interface SpillStore {
208
+ set(id: string, value: string): Awaitable<void>;
209
+ get(id: string): Awaitable<string | undefined>;
210
+ }
211
+ export function createMemorySpillStore(): SpillStore;
212
+ export const DEFAULT_LOOP_THRESHOLDS: Readonly<{ reminder: number; firmReminder: number; stop: number }>;
213
+ export const DEFAULT_SPILL_THRESHOLD: number;
214
+
189
215
  export function runAgentLoop(options: AgentLoopOptions): Promise<string>;
190
216
 
191
217
  export type ActionStatus = 'proposed' | 'approved' | 'rejected' | 'executing' | 'executed' | 'failed';
@@ -576,7 +602,7 @@ export function askChatModel(
576
602
  target: { url: string; key: string; model: string; extra?: Record<string, unknown> },
577
603
  request: { system?: string; messages: ChatMessage[]; tools?: Array<Record<string, unknown>>; maxTokens?: number; temperature?: number },
578
604
  io: { fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number }
579
- ): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
605
+ ): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean; retryAfterMs?: number }>;
580
606
 
581
607
  export function readToolArguments(raw: unknown): { args: Record<string, unknown> | null; invalid: boolean; reason?: 'not_json' | 'not_object'; detail?: string };
582
608
 
@@ -624,12 +650,14 @@ export function createOpenAICompatibleProvider(options: ChatProviderOptions & {
624
650
  export function askGeminiModel(
625
651
  model: string,
626
652
  request: ChatRequest,
627
- io: { key: string; fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number; endpoint?: string; noSystemInstruction?: (model: string) => boolean }
628
- ): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean }>;
653
+ io: { key: string; fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number; endpoint?: string; noSystemInstruction?: (model: string) => boolean; extra?: Record<string, unknown> }
654
+ ): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean; retryAfterMs?: number }>;
629
655
 
630
656
  export function createGeminiProvider(options: ChatProviderOptions & {
631
657
  id?: string;
632
658
  endpoint?: string;
659
+ external?: boolean;
660
+ extra?: Record<string, unknown>;
633
661
  /** Défaut : les modèles Gemma, qui ne prennent pas de consigne système. */
634
662
  noSystemInstruction?: (model: string) => boolean;
635
663
  }): Provider;
@@ -651,6 +679,7 @@ export interface NativeTool<Ctx = Record<string, unknown>> {
651
679
  description: string;
652
680
  parameters: { type: 'object'; [key: string]: unknown };
653
681
  kind: NativeToolKind;
682
+ risk?: DeclaredToolRisk;
654
683
  summary?: (args: Record<string, unknown>) => Record<string, string | number>;
655
684
  run(args: Record<string, unknown>, ctx: Ctx & { signal: AbortSignal }): Awaitable<NativeToolResult | null | undefined>;
656
685
  perform?(args: Record<string, unknown>, ctx: Ctx): Awaitable<NativeToolResult | null | undefined>;
@@ -658,7 +687,7 @@ export interface NativeTool<Ctx = Record<string, unknown>> {
658
687
  }
659
688
 
660
689
  export const NATIVE_TOOL_KINDS: string[];
661
- export function validateNativeTools<T extends NativeTool<any>>(tools: T[], options?: { kinds?: string[]; requireSummary?: boolean }): T[];
690
+ export function validateNativeTools<T extends NativeTool<any>>(tools: T[], options?: { kinds?: string[]; requireSummary?: boolean; requireRisk?: boolean }): T[];
662
691
  export function toolSpecs(tools: NativeTool<any>[]): Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
663
692
  export function stepParams(tool: NativeTool<any> | null | undefined, args: unknown, options?: { max?: number }): Record<string, string | number>;
664
693
 
@@ -681,6 +710,9 @@ export interface ToolMessage {
681
710
  export function createToolCaller<Ctx = Record<string, unknown>>(options: {
682
711
  tools: Map<string, NativeTool<Ctx>> | NativeTool<Ctx>[];
683
712
  context?: Ctx;
713
+ confirmationPolicy?: 'always' | 'never' | { threshold: ToolRisk };
714
+ exposure?: { untrusted: boolean };
715
+ readsUntrusted?: (tool: NativeTool<Ctx>, found: NativeToolResult | null | undefined) => boolean;
684
716
  signal?: AbortSignal;
685
717
  timeoutMs?: number;
686
718
  now?: () => number;
@@ -734,3 +766,340 @@ export function searchSerper(
734
766
  search: { query: string; sites?: string[]; hl?: string; num?: number },
735
767
  io: { key: string | null | undefined; fetch: FetchLike; accept?: (result: WebResult, url: URL) => boolean; timeoutMs?: number; endpoint?: string }
736
768
  ): Promise<WebResult[]>;
769
+
770
+ // Serveur llama.cpp (inférence CPU) : src/llamaCpp.js
771
+ export const DEFAULT_LLAMA_CPP_URL: string;
772
+ export function normalizeLlamaCppUrl(value: string): string;
773
+
774
+ export interface LlamaCppConfigInput {
775
+ /** Base du serveur, avec ou sans `/v1` (défaut http://127.0.0.1:8080). */
776
+ baseUrl?: string;
777
+ apiKey?: string | null;
778
+ model?: string | null;
779
+ timeoutMs?: number;
780
+ healthTimeoutMs?: number;
781
+ }
782
+ export interface LlamaCppConfig {
783
+ readonly id: 'llama.cpp';
784
+ readonly baseUrl: string;
785
+ readonly apiKey: string | null;
786
+ readonly model: string | null;
787
+ readonly timeoutMs: number;
788
+ readonly healthTimeoutMs: number;
789
+ }
790
+ export function createLlamaCppConfig(input?: LlamaCppConfigInput): LlamaCppConfig;
791
+
792
+ export type LocalLlmErrorCode = 'UNREACHABLE' | 'TIMEOUT' | 'UNAUTHORIZED' | 'LOADING' | 'HTTP_ERROR' | 'INVALID_RESPONSE';
793
+ export class LocalLlmError extends Error {
794
+ code: LocalLlmErrorCode;
795
+ status: number | null;
796
+ }
797
+
798
+ export interface LlamaCppChatMessage { role: 'system' | 'user' | 'assistant' | 'tool'; content: string; [key: string]: unknown }
799
+ export interface LlamaCppChatOptions { model?: string; temperature?: number; max_tokens?: number; [key: string]: unknown }
800
+ export interface LlamaCppChatResult {
801
+ text: string;
802
+ finishReason: string | null;
803
+ usage: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number } | null;
804
+ model: string | null;
805
+ }
806
+ export interface LlamaCppHealthState {
807
+ ok: boolean;
808
+ status: 'ok' | 'loading' | 'unauthorized' | 'error' | 'unreachable' | 'timeout';
809
+ latencyMs: number;
810
+ httpStatus?: number;
811
+ message?: string;
812
+ }
813
+ export interface LlamaCppProvider {
814
+ config: LlamaCppConfig;
815
+ health(): Promise<LlamaCppHealthState>;
816
+ waitUntilReady(options?: { timeoutMs?: number; intervalMs?: number }): Promise<LlamaCppHealthState>;
817
+ listModels(): Promise<Array<{ id: string; ownedBy: string | null }>>;
818
+ chat(messages: LlamaCppChatMessage[], options?: LlamaCppChatOptions): Promise<LlamaCppChatResult>;
819
+ chatStream(messages: LlamaCppChatMessage[], options?: LlamaCppChatOptions): AsyncGenerator<string, void, undefined>;
820
+ toOpenAICompatible(): { baseURL: string; apiKey: string; model: string | null };
821
+ }
822
+ export function createLlamaCppProvider(options?: LlamaCppConfigInput & {
823
+ fetch?: (url: string, init: object) => Awaitable<Response>;
824
+ sleep?: (ms: number) => Promise<void>;
825
+ }): LlamaCppProvider;
826
+
827
+ /* Configured routing, local model services and voice. */
828
+ export type AiUsage = 'quick' | 'chat' | 'tools' | 'pilot' | 'json' | 'vision';
829
+ export interface RoutingState {
830
+ day: string;
831
+ rpmWindow: number[];
832
+ rpdUsed: number;
833
+ tpdUsed: number;
834
+ cooldownUntil: number;
835
+ degradedUntil: number;
836
+ failures: number;
837
+ disabled: boolean;
838
+ }
839
+ /** update must be atomic across all users of the store. The callback is synchronous
840
+ * and side-effect free: a CAS adapter may call it more than once. */
841
+ export interface RoutingStateStore {
842
+ read(key: string): Awaitable<RoutingState | null>;
843
+ update<T>(key: string, change: (state: RoutingState | null) => { state: RoutingState | null; value?: T }): Awaitable<T | undefined>;
844
+ }
845
+ export function createMemoryRoutingStore(): RoutingStateStore;
846
+ export interface RoutingRedisClient {
847
+ get(key: string): Promise<string | null>;
848
+ eval(script: string, options: { keys: string[]; arguments: string[] }): Promise<unknown>;
849
+ }
850
+ export function createRedisRoutingStore(options: { client: RoutingRedisClient; prefix?: string; ttlMs?: number; maxRetries?: number }): RoutingStateStore;
851
+ export interface RoutingPgConnection {
852
+ query(sql: string, params?: unknown[]): Promise<{ rows: Array<{ state?: RoutingState }> }>;
853
+ release(): void;
854
+ }
855
+ export interface RoutingPgPool {
856
+ query(sql: string, params?: unknown[]): Promise<{ rows: Array<{ state?: RoutingState }> }>;
857
+ connect(): Promise<RoutingPgConnection>;
858
+ }
859
+ export function createPostgresRoutingStore(options: { pool: RoutingPgPool; table?: string }): RoutingStateStore & { initialize(): Promise<void> };
860
+ export type AiKeys = string[] | string | ((ctx: Record<string, unknown>) => Awaitable<string[] | string | null | undefined>);
861
+ export interface ConfiguredProviderModel extends ProviderModel {
862
+ vision?: boolean;
863
+ visionOnly?: boolean;
864
+ extra?: Record<string, unknown>;
865
+ maxTokens?: number;
866
+ disabled?: boolean;
867
+ preview?: boolean;
868
+ languages?: string[];
869
+ noAnalytics?: boolean;
870
+ maxInputTokens?: number;
871
+ }
872
+ export interface ConfiguredProvider {
873
+ id: string;
874
+ format: 'openai' | 'gemini';
875
+ /** Full OpenAI chat URL, or Gemini models endpoint (without the model). */
876
+ url: string;
877
+ keys?: AiKeys;
878
+ keysByUsage?: Record<string, AiKeys>;
879
+ keyLane?: (ctx: Record<string, unknown>) => string | null | undefined;
880
+ /** False by default. Local providers work without API credentials. */
881
+ local?: boolean;
882
+ vision?: boolean;
883
+ extra?: Record<string, unknown>;
884
+ models: ConfiguredProviderModel[];
885
+ /** Share model quotas between credentials when they belong to one account. */
886
+ sharedKeyQuotas?: boolean;
887
+ maxConcurrent?: number;
888
+ maxQueue?: number;
889
+ /** Provider variable stem used by readAiConfigFromEnv. */
890
+ envName?: string;
891
+ }
892
+ export interface ConfiguredRouterConfig {
893
+ cooldownJitterMs?: number;
894
+ providers?: ConfiguredProvider[];
895
+ usages?: Partial<Record<AiUsage, RouteCandidate[]>>;
896
+ intentRouting?: Record<string, { preferred: string[] }>;
897
+ store?: RoutingStateStore;
898
+ statePrefix?: string;
899
+ fetch?: FetchLike;
900
+ now?: () => number;
901
+ quotaMargin?: number | { rpm?: number; rpd?: number; tpd?: number };
902
+ tokenBuffer?: number;
903
+ cooldownMs?: number;
904
+ degradedMs?: number;
905
+ maxFailures?: number;
906
+ waitedTimeoutMs?: number;
907
+ backgroundTimeoutMs?: number;
908
+ whenAllCooling?: 'skip' | 'try';
909
+ reserveVision?: boolean;
910
+ }
911
+ export interface ConfiguredRouteOptions {
912
+ usage?: AiUsage;
913
+ complexity?: string;
914
+ intent?: string;
915
+ candidates?: RouteCandidate[];
916
+ exclude?: string[];
917
+ language?: string;
918
+ hasAnalytics?: boolean;
919
+ estimatedTokens?: number;
920
+ purpose?: string;
921
+ waitedOn?: boolean;
922
+ timeoutMs?: number;
923
+ signal?: AbortSignal;
924
+ context?: Record<string, unknown>;
925
+ json?: boolean;
926
+ fallbackWithoutTools?: boolean;
927
+ accepts?: (answer: DetailedAnswer) => boolean;
928
+ }
929
+ export interface ConfiguredRouteResult extends RouteResult<DetailedAnswer> {
930
+ stateKey: string;
931
+ usage: AiUsage;
932
+ complexity: string;
933
+ fallback: boolean;
934
+ }
935
+ export interface ConfiguredRouter {
936
+ route(input: ChatRequest | string, options?: ConfiguredRouteOptions, context?: Record<string, unknown>): Promise<ConfiguredRouteResult>;
937
+ ask(input: ChatRequest | string, options?: ConfiguredRouteOptions, context?: Record<string, unknown>): Promise<DetailedAnswer>;
938
+ getStats(): Promise<Record<string, RoutingState>>;
939
+ /** Resets only state keys seen by this instance. */
940
+ reset(): Promise<void>;
941
+ stop(): void;
942
+ store: RoutingStateStore;
943
+ }
944
+ export function createConfiguredRouter(config?: ConfiguredRouterConfig): ConfiguredRouter;
945
+ export function estimateRequestComplexity(input: ChatRequest | string): 'simple' | 'medium' | 'complex';
946
+ export function estimateRequestTokens(request: ChatRequest): number;
947
+ export function readEnvironmentKeys(env: Record<string, string | undefined>, name: string): string[];
948
+ export interface AiEnvironmentConfig extends ConfiguredRouterConfig {
949
+ localModels: LocalModelsOptions;
950
+ language: ServiceLanguageOptions;
951
+ voice: SpeechServiceOptions & TranscriptionServiceOptions;
952
+ }
953
+ export function readAiConfigFromEnv(options?: { env?: Record<string, string | undefined>; prefix?: string }): AiEnvironmentConfig;
954
+
955
+ export class AiServiceError extends Error {
956
+ constructor(code: string, status?: number | null);
957
+ code: string;
958
+ status: number | null;
959
+ statusCode: number | null;
960
+ }
961
+ export type ServiceFetch = (url: string, init: RequestInit) => Promise<Pick<Response, 'ok' | 'status' | 'json' | 'arrayBuffer'>>;
962
+ export function createTokenFileReader(options?: {
963
+ tokenFile?: string;
964
+ read?: (path: string, encoding: 'utf8') => Promise<string>;
965
+ now?: () => number;
966
+ refreshMs?: number;
967
+ }): () => Promise<string | null>;
968
+ export interface ServiceRequestOptions {
969
+ fetch?: ServiceFetch;
970
+ timeoutMs?: number;
971
+ signal?: AbortSignal;
972
+ headers?: Record<string, string>;
973
+ body?: unknown;
974
+ rawBody?: BodyInit;
975
+ read?: 'json' | 'bytes';
976
+ }
977
+ export function serviceRequest(url: string | null | undefined, options?: ServiceRequestOptions & { read?: 'json' }): Promise<any>;
978
+ export function serviceRequest(url: string | null | undefined, options: ServiceRequestOptions & { read: 'bytes' }): Promise<Buffer>;
979
+ export function endpoint(base: string | null | undefined, path: string): string | null;
980
+ export const LOCAL_VECTOR_MODEL: string;
981
+ export const LOCAL_VECTOR_DIMENSIONS: number;
982
+ export function validPcmAudio(audio: unknown): boolean;
983
+ export interface LocalModelsOptions {
984
+ baseUrl?: string;
985
+ tokenFile?: string;
986
+ readTokenFile?: (path: string, encoding: 'utf8') => Promise<string>;
987
+ tokenRefreshMs?: number;
988
+ timeoutMs?: number;
989
+ maxFailures?: number;
990
+ cooldownMs?: number;
991
+ now?: () => number;
992
+ fetch?: ServiceFetch;
993
+ vectorModel?: string;
994
+ vectorDimensions?: number;
995
+ onError?: (error: AiServiceError, route: string) => void;
996
+ }
997
+ export interface LocalCallOptions { timeoutMs?: number; signal?: AbortSignal }
998
+ export interface NliPair { premisse: string; hypothese: string }
999
+ export interface NliResult { accord: number; neutre: number; contradiction: number }
1000
+ export interface LocalEntity { texte: string; type: string; debut: number; fin: number; score: number }
1001
+ export type LocalVectors = number[][] & { readonly modele: string; readonly dimensions: number };
1002
+ export interface LocalTranscription { texte: string; langue: string; logprob: number; sansParole: number; dureeMs: number }
1003
+ export interface LocalModelsClient {
1004
+ rerank(question: string, passages: string[], options?: LocalCallOptions): Promise<number[] | null>;
1005
+ compare(pairs: Array<{ premise: string; hypothesis: string }>, options?: LocalCallOptions): Promise<Array<{ entailment: number; neutral: number; contradiction: number }> | null>;
1006
+ entities(text: string, labels: string[], options?: LocalCallOptions): Promise<Array<{ text: string; type: string; start: number; end: number; score: number }> | null>;
1007
+ embed(texts: string[], options?: LocalCallOptions): Promise<LocalVectors | null>;
1008
+ reclasser(question: string, passages: string[], options?: LocalCallOptions): Promise<number[] | null>;
1009
+ nli(pairs: NliPair[], options?: LocalCallOptions): Promise<NliResult[] | null>;
1010
+ comparer(pairs: NliPair[], options?: LocalCallOptions): Promise<NliResult[] | null>;
1011
+ entites(text: string, labels: string[], options?: LocalCallOptions): Promise<LocalEntity[] | null>;
1012
+ vecteurs(texts: string[], options?: LocalCallOptions): Promise<LocalVectors | null>;
1013
+ transcrire(audio: string, options?: LocalCallOptions & { langue?: string; vocabulaire?: string }): Promise<LocalTranscription | null>;
1014
+ disponible(route: string): boolean;
1015
+ available(route: string): boolean;
1016
+ }
1017
+ export function createLocalModelsClient(options?: LocalModelsOptions): LocalModelsClient;
1018
+ export const DEFAULT_LANGUAGE_WORDS: Readonly<Record<string, string[]>>;
1019
+ export interface ServiceLanguageOptions extends Omit<Parameters<typeof createLanguageDetector>[0], 'words' | 'identify'> {
1020
+ words?: Record<string, string[]>;
1021
+ baseUrl?: string;
1022
+ fetch?: ServiceFetch;
1023
+ timeoutMs?: number;
1024
+ }
1025
+ export function createServiceLanguageDetector(options?: ServiceLanguageOptions): LanguageDetector;
1026
+
1027
+ export interface VoiceProviderOptions {
1028
+ keys?: string[] | string | (() => Awaitable<string[] | string | undefined | null>);
1029
+ models?: string[];
1030
+ timeoutMs?: number;
1031
+ cooldownMs?: number;
1032
+ }
1033
+ export interface TranscriptionServiceOptions {
1034
+ local?: Pick<LocalModelsClient, 'transcrire'>;
1035
+ localModels?: LocalModelsOptions;
1036
+ localTimeoutMs?: number;
1037
+ groq?: VoiceProviderOptions & { url?: string };
1038
+ cloudflare?: VoiceProviderOptions & { url?: string | ((model: string) => string) };
1039
+ fetch?: ServiceFetch;
1040
+ now?: () => number;
1041
+ maxAudioBytes?: number;
1042
+ noSpeechThreshold?: number;
1043
+ logprobThreshold?: number;
1044
+ stockPhrases?: readonly string[];
1045
+ }
1046
+ export interface TranscriptionInput {
1047
+ /** PCM16 little-endian, 16kHz mono by default; base64 or bytes. */
1048
+ audio: string | Uint8Array;
1049
+ format?: 'pcm16' | 'wav' | 'file';
1050
+ language?: string;
1051
+ vocabulary?: string;
1052
+ filename?: string;
1053
+ mimeType?: string;
1054
+ signal?: AbortSignal;
1055
+ allowRemote?: boolean;
1056
+ }
1057
+ export interface TranscriptionResult {
1058
+ text: string;
1059
+ language: string | null;
1060
+ provider: 'local' | 'groq' | 'cloudflare';
1061
+ model: string;
1062
+ fallback: boolean;
1063
+ confidence?: number;
1064
+ noSpeech?: boolean;
1065
+ }
1066
+ export function createTranscriptionService(options?: TranscriptionServiceOptions): { transcribe(input: TranscriptionInput): Promise<TranscriptionResult> };
1067
+ export interface SpeechServiceOptions {
1068
+ /** Synthesis order. Default: Gemini (online) first, Piper (local) as fallback. */
1069
+ order?: Array<'gemini' | 'piper'>;
1070
+ piper?: {
1071
+ baseUrl?: string;
1072
+ tokenFile?: string;
1073
+ readTokenFile?: (path: string, encoding: 'utf8') => Promise<string>;
1074
+ timeoutMs?: number;
1075
+ cooldownMs?: number;
1076
+ };
1077
+ gemini?: VoiceProviderOptions & { endpoint?: string; voice?: string };
1078
+ now?: () => number;
1079
+ fetch?: ServiceFetch;
1080
+ prepareText?: (text: string) => string;
1081
+ }
1082
+ export interface SpeechResult {
1083
+ audio: Buffer;
1084
+ format: 'wav';
1085
+ mimeType: 'audio/wav';
1086
+ sampleRate: number;
1087
+ channels: number;
1088
+ provider: 'piper' | 'gemini';
1089
+ model: string | null;
1090
+ fallback: boolean;
1091
+ }
1092
+ export function createSpeechService(options?: SpeechServiceOptions): { synthesize(input: { text: string; language?: string; signal?: AbortSignal; allowRemote?: boolean }): Promise<SpeechResult> };
1093
+ export function pcmToWav(pcm: Uint8Array, options?: { sampleRate?: number; channels?: number }): Buffer;
1094
+ export function readPcmWav(audio: Uint8Array): { pcm: Buffer; sampleRate: number; channels: number };
1095
+ export function speakableText(text: string, maxChars?: number): string;
1096
+ export function doubtfulTranscription(text: string, options?: { stockPhrases?: readonly string[] }): boolean;
1097
+ export const WHISPER_STOCK_PHRASES: readonly string[];
1098
+ export function toolRiskOf(tool: { risk?: string } | null | undefined): ToolRisk;
1099
+ export function waitsForToolConfirmation(tool: { risk?: string; kind?: string } | null | undefined, options?: { policy?: 'always' | 'never' | { threshold: ToolRisk }; untrusted?: boolean }): boolean;
1100
+
1101
+ export function readRetryAfter(response: { headers?: { get(name: string): string | null } }, now?: number): number | null;
1102
+ export function createInferenceQueue(options?: { maxConcurrent?: number; maxQueue?: number }): {
1103
+ run<T>(task: () => Awaitable<T>, options?: { signal?: AbortSignal }): Promise<T>;
1104
+ stats(): { active: number; waiting: number };
1105
+ };
package/src/index.js CHANGED
@@ -14,8 +14,17 @@ module.exports = {
14
14
  ...require('./language'),
15
15
  ...require('./askLimit'),
16
16
  ...require('./openaiCompatible'),
17
+ ...require('./llamaCpp'),
17
18
  ...require('./gemini'),
18
19
  ...require('./nativeTools'),
19
20
  ...require('./eventStream'),
20
- ...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')
21
30
  };
@@ -0,0 +1,192 @@
1
+ 'use strict';
2
+
3
+ /* global AbortController, TextDecoder */
4
+
5
+ /*
6
+ * Fournisseur d'un `llama-server` (llama.cpp), inférence sur CPU, API compatible
7
+ * OpenAI. Ce n'est pas un doublon de openaiCompatible.js : celui-ci branche un
8
+ * modèle dans le routeur et avale les erreurs HTTP (il rend `{ status }`), alors
9
+ * qu'un serveur qu'on héberge soi-même a besoin de sa santé (/health), du
10
+ * chargement du modèle (503), de la liste de ses modèles et d'erreurs typées.
11
+ * Pour router ce serveur, `toOpenAICompatible()` donne l'adresse et la clé à
12
+ * `createOpenAICompatibleProvider`.
13
+ */
14
+
15
+ const DEFAULT_LLAMA_CPP_URL = 'http://127.0.0.1:8080';
16
+
17
+ /**
18
+ * `llama-server` expose l'API OpenAI sous /v1 et sa santé sous /health (hors
19
+ * /v1). On garde donc une base nue et on ajoute les chemins nous-mêmes : que
20
+ * l'utilisateur écrive `http://hote:8080` ou `http://hote:8080/v1`, c'est pareil.
21
+ */
22
+ function normalizeLlamaCppUrl(value) {
23
+ let url;
24
+ try {
25
+ url = new URL(value);
26
+ } catch {
27
+ throw new TypeError('INVALID_BASE_URL');
28
+ }
29
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new TypeError('INVALID_BASE_URL');
30
+ return url.toString().replace(/\/+$/, '').replace(/\/v1$/, '');
31
+ }
32
+
33
+ function createLlamaCppConfig({ baseUrl = DEFAULT_LLAMA_CPP_URL, apiKey = null, model = null, timeoutMs = 120_000, healthTimeoutMs = 5_000 } = {}) {
34
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new RangeError('INVALID_TIMEOUT');
35
+ if (!Number.isFinite(healthTimeoutMs) || healthTimeoutMs <= 0) throw new RangeError('INVALID_TIMEOUT');
36
+ return Object.freeze({
37
+ id: 'llama.cpp',
38
+ baseUrl: normalizeLlamaCppUrl(baseUrl),
39
+ apiKey: apiKey || null,
40
+ model: model || null,
41
+ timeoutMs,
42
+ healthTimeoutMs
43
+ });
44
+ }
45
+
46
+
47
+ /** Erreur du fournisseur local ; `code` : UNREACHABLE, TIMEOUT, UNAUTHORIZED, LOADING, HTTP_ERROR, INVALID_RESPONSE. */
48
+ class LocalLlmError extends Error {
49
+ constructor(code, message, { status = null, cause } = {}) {
50
+ super(message, cause ? { cause } : undefined);
51
+ this.name = 'LocalLlmError';
52
+ this.code = code;
53
+ this.status = status;
54
+ }
55
+ }
56
+
57
+
58
+ const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
59
+
60
+ /**
61
+ * Client d'un `llama-server` (llama.cpp) : API compatible OpenAI, inférence sur
62
+ * CPU. Aucune dépendance : `fetch` est injectable pour les tests.
63
+ */
64
+ function createLlamaCppProvider(options = {}) {
65
+ const config = createLlamaCppConfig(options);
66
+ const fetchImpl = options.fetch || globalThis.fetch;
67
+ const sleep = options.sleep || wait;
68
+ if (typeof fetchImpl !== 'function') throw new TypeError('FETCH_REQUIRED');
69
+
70
+ function headers(extra) {
71
+ return { ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}), ...extra };
72
+ }
73
+
74
+ async function request(path, { method = 'GET', body, timeoutMs = config.timeoutMs } = {}) {
75
+ const controller = new AbortController();
76
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
77
+ try {
78
+ return await fetchImpl(`${config.baseUrl}${path}`, {
79
+ method,
80
+ headers: headers(body ? { 'Content-Type': 'application/json' } : {}),
81
+ body: body ? JSON.stringify(body) : undefined,
82
+ signal: controller.signal
83
+ });
84
+ } catch (error) {
85
+ if (controller.signal.aborted) throw new LocalLlmError('TIMEOUT', `Pas de réponse en ${timeoutMs} ms`, { cause: error });
86
+ throw new LocalLlmError('UNREACHABLE', `Serveur injoignable (${config.baseUrl})`, { cause: error });
87
+ } finally {
88
+ clearTimeout(timer);
89
+ }
90
+ }
91
+
92
+ async function failure(response) {
93
+ let detail = '';
94
+ try { detail = (await response.json())?.error?.message || ''; } catch { /* corps non JSON */ }
95
+ if (response.status === 401 || response.status === 403) return new LocalLlmError('UNAUTHORIZED', 'Clé API refusée', { status: response.status });
96
+ if (response.status === 503) return new LocalLlmError('LOADING', detail || 'Modèle en cours de chargement', { status: 503 });
97
+ return new LocalLlmError('HTTP_ERROR', detail || `Réponse HTTP ${response.status}`, { status: response.status });
98
+ }
99
+
100
+ async function json(response) {
101
+ try {
102
+ return await response.json();
103
+ } catch (error) {
104
+ throw new LocalLlmError('INVALID_RESPONSE', 'Réponse non JSON', { cause: error });
105
+ }
106
+ }
107
+
108
+ /** `{ ok, status }` — status : ok | loading | unauthorized | error | unreachable | timeout. Ne lance jamais. */
109
+ async function health() {
110
+ const started = Date.now();
111
+ try {
112
+ const response = await request('/health', { timeoutMs: config.healthTimeoutMs });
113
+ const latencyMs = Date.now() - started;
114
+ if (response.ok) return { ok: true, status: 'ok', latencyMs };
115
+ const error = await failure(response);
116
+ return { ok: false, status: error.code === 'LOADING' ? 'loading' : error.code === 'UNAUTHORIZED' ? 'unauthorized' : 'error', httpStatus: response.status, latencyMs, message: error.message };
117
+ } catch (error) {
118
+ return { ok: false, status: error.code === 'TIMEOUT' ? 'timeout' : 'unreachable', latencyMs: Date.now() - started, message: error.message };
119
+ }
120
+ }
121
+
122
+ /** Attend que le modèle soit chargé (le premier démarrage peut prendre une minute). */
123
+ async function waitUntilReady({ timeoutMs = 120_000, intervalMs = 2_000 } = {}) {
124
+ const deadline = Date.now() + timeoutMs;
125
+ for (;;) {
126
+ const state = await health();
127
+ if (state.ok) return state;
128
+ if (state.status === 'unauthorized') throw new LocalLlmError('UNAUTHORIZED', state.message, { status: state.httpStatus });
129
+ if (Date.now() + intervalMs > deadline) throw new LocalLlmError('TIMEOUT', `Serveur pas prêt après ${timeoutMs} ms (${state.status})`);
130
+ await sleep(intervalMs);
131
+ }
132
+ }
133
+
134
+ /** Modèles servis, au format OpenAI : `[{ id, ownedBy }]`. */
135
+ async function listModels() {
136
+ const response = await request('/v1/models');
137
+ if (!response.ok) throw await failure(response);
138
+ const payload = await json(response);
139
+ if (!Array.isArray(payload?.data)) throw new LocalLlmError('INVALID_RESPONSE', 'Liste de modèles absente');
140
+ return payload.data.map((item) => ({ id: item.id, ownedBy: item.owned_by ?? null }));
141
+ }
142
+
143
+ function chatBody(messages, { model, stream = false, ...rest } = {}) {
144
+ if (!Array.isArray(messages) || messages.length === 0) throw new TypeError('MESSAGES_REQUIRED');
145
+ // llama-server ne sert qu'un modèle : le champ « model » est facultatif chez lui, on le passe s'il est connu.
146
+ const name = model || config.model;
147
+ return { ...(name ? { model: name } : {}), messages, stream, ...rest };
148
+ }
149
+
150
+ async function chat(messages, options = {}) {
151
+ const response = await request('/v1/chat/completions', { method: 'POST', body: chatBody(messages, { ...options, stream: false }) });
152
+ if (!response.ok) throw await failure(response);
153
+ const payload = await json(response);
154
+ const choice = payload?.choices?.[0];
155
+ if (!choice?.message) throw new LocalLlmError('INVALID_RESPONSE', 'Réponse sans choix');
156
+ return { text: choice.message.content ?? '', finishReason: choice.finish_reason ?? null, usage: payload.usage ?? null, model: payload.model ?? null };
157
+ }
158
+
159
+ /** Itère sur les fragments de texte (SSE `data: {...}` jusqu'à `[DONE]`). */
160
+ async function* chatStream(messages, options = {}) {
161
+ const response = await request('/v1/chat/completions', { method: 'POST', body: chatBody(messages, { ...options, stream: true }) });
162
+ if (!response.ok) throw await failure(response);
163
+ const decoder = new TextDecoder();
164
+ let buffer = '';
165
+ for await (const chunk of response.body) {
166
+ buffer += decoder.decode(chunk, { stream: true });
167
+ const lines = buffer.split('\n');
168
+ buffer = lines.pop();
169
+ for (const line of lines) {
170
+ if (!line.startsWith('data:')) continue;
171
+ const data = line.slice(5).trim();
172
+ if (data === '[DONE]') return;
173
+ let parsed;
174
+ try { parsed = JSON.parse(data); } catch (error) { throw new LocalLlmError('INVALID_RESPONSE', 'Fragment SSE illisible', { cause: error }); }
175
+ const delta = parsed?.choices?.[0]?.delta?.content;
176
+ if (delta) yield delta;
177
+ }
178
+ }
179
+ }
180
+
181
+ /** Configuration à donner à tout client « compatible OpenAI » (SDK, LiteLLM, autre paquet). */
182
+ function toOpenAICompatible() {
183
+ return { baseURL: `${config.baseUrl}/v1`, apiKey: config.apiKey || 'sans-cle', model: config.model };
184
+ }
185
+
186
+ return { config, health, waitUntilReady, listModels, chat, chatStream, toOpenAICompatible };
187
+ }
188
+
189
+
190
+ module.exports = {
191
+ DEFAULT_LLAMA_CPP_URL, normalizeLlamaCppUrl, createLlamaCppConfig, createLlamaCppProvider, LocalLlmError
192
+ };