@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/README.md +458 -6
- package/deploy/llama-cpp/.env.example +10 -0
- package/deploy/llama-cpp/docker-compose.yml +47 -0
- package/package.json +7 -4
- package/src/agentLoop.js +101 -5
- package/src/aiConfig.js +72 -0
- package/src/gemini.js +9 -3
- package/src/index.d.ts +374 -5
- package/src/index.js +10 -1
- package/src/llamaCpp.js +192 -0
- package/src/localModels.js +99 -0
- package/src/managedRouter.js +258 -0
- 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/toolRegistry.js +13 -2
- package/src/voice.js +181 -0
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
|
|
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
|
};
|
package/src/llamaCpp.js
ADDED
|
@@ -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
|
+
};
|