@astratra/ai 1.16.0 → 2.0.1
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 +31 -15
- package/package.json +2 -2
- package/src/aiConfig.js +36 -3
- package/src/index.d.ts +35 -4
- package/src/mcpClient.js +9 -21
- package/src/openaiCompatible.js +2 -2
- package/src/voice.js +117 -29
package/README.md
CHANGED
|
@@ -216,13 +216,12 @@ schémas stricts produits par `toolSpecs` passent donc tels quels.
|
|
|
216
216
|
**Signatures de pensée (Gemini 3, 1.12.0)** : chaque appel d'outil de Gemini 3
|
|
217
217
|
porte une signature, à rendre telle quelle au tour suivant, sinon Gemini répond
|
|
218
218
|
400. Elle arrive dans `toolCalls[i].signature` (directement chez Gemini, par
|
|
219
|
-
l'API compatible OpenAI de Google, ou par
|
|
219
|
+
l'API compatible OpenAI de Google, ou par une passerelle qui la relaie) : **gardez
|
|
220
220
|
l'appel tel quel** dans le message `assistant` de l'historique, elle repart
|
|
221
221
|
avec lui (`thoughtSignature` chez Gemini, `extra_content.google.thought_signature`
|
|
222
222
|
au format OpenAI). Au format OpenAI, elle n'est envoyée qu'à `*.googleapis.com`,
|
|
223
223
|
ou à une cible qui le demande : `thoughtSignatures: true` (dans la cible
|
|
224
|
-
d'`askChatModel` ou les options de `createOpenAICompatibleProvider` ;
|
|
225
|
-
`modeleDiscussion()` de `@astratra/centrale` 1.7.0 le donne) ; jamais à un
|
|
224
|
+
d'`askChatModel` ou les options de `createOpenAICompatibleProvider`) ; jamais à un
|
|
226
225
|
autre fournisseur, qui pourrait refuser le champ. Un premier appel sans
|
|
227
226
|
signature (venu d'un autre fournisseur) part chez Gemini avec la valeur de
|
|
228
227
|
contournement de Google (`skip_thought_signature_validator`), sauf pour Gemma.
|
|
@@ -998,17 +997,24 @@ object, never an `.env` file. `ARIA_` or another prefix works identically.
|
|
|
998
997
|
| `IA_MODELS_URL`, `IA_MODELS_TOKEN_FILE` | Optional local model server and its Bearer file |
|
|
999
998
|
| `IA_TTS_URL`, `IA_TTS_TOKEN_FILE` | Optional Piper server and Bearer file |
|
|
1000
999
|
| `IA_LANGUAGE_URL`, `IA_LANGUAGE_TIMEOUT_MS` | Optional fastText server; default timeout 800 |
|
|
1001
|
-
| `IA_GROQ_WHISPER_URL`, `IA_GROQ_WHISPER_MODELS` | Full endpoint, JSON model IDs
|
|
1002
|
-
| `IA_CLOUDFLARE_ACCOUNT_ID`, `IA_CLOUDFLARE_WHISPER_URL` | Account for the
|
|
1003
|
-
| `IA_GEMINI_TTS_ENDPOINT`, `IA_GEMINI_TTS_MODELS`, `IA_GEMINI_TTS_VOICE` | Models base URL, JSON model IDs
|
|
1000
|
+
| `IA_GROQ_WHISPER_URL`, `IA_GROQ_WHISPER_MODELS` | Full endpoint (default: Groq's official transcription address), JSON model IDs (**required**, no default) |
|
|
1001
|
+
| `IA_CLOUDFLARE_ACCOUNT_ID`, `IA_CLOUDFLARE_WHISPER_URL`, `IA_CLOUDFLARE_WHISPER_MODELS` | Account for the Workers AI run address (the model is appended), or an explicit full URL; JSON model IDs (**required**, no default) |
|
|
1002
|
+
| `IA_GEMINI_TTS_ENDPOINT`, `IA_GEMINI_TTS_MODELS`, `IA_GEMINI_TTS_VOICE` | Models base URL (default: Google's official address), JSON model IDs and voice name (both **required**, no default) |
|
|
1003
|
+
| `IA_TRANSCRIPTION_ORDER`, `IA_SPEECH_ORDER` | JSON order of services, e.g. `["local","groq"]`, `["piper","gemini"]`; required when several services are usable |
|
|
1004
1004
|
|
|
1005
1005
|
Voice uses `IA_GROQ_KEY[_N]`, `IA_CLOUDFLARE_KEY[_N]` and
|
|
1006
1006
|
`IA_GEMINI_KEY[_N]`. No provider catalogue is auto-created: `IA_PROVIDERS`
|
|
1007
1007
|
is required to configure text routing. Voice/local sections are returned as
|
|
1008
1008
|
`config.voice`, `config.localModels`, `config.language`. Inject the store in
|
|
1009
1009
|
code after reading the configuration. Invalid JSON is reported by variable
|
|
1010
|
-
name only, never by its value.
|
|
1011
|
-
|
|
1010
|
+
name only, never by its value.
|
|
1011
|
+
|
|
1012
|
+
**Nothing is chosen for you.** No model, no voice and no order of services is
|
|
1013
|
+
written in the package: each comes from your configuration. Only the official
|
|
1014
|
+
address of a service you enabled has a default, because an address is not a
|
|
1015
|
+
choice. A key set without the model (or, for Gemini, the voice) its service
|
|
1016
|
+
needs is listed in `config.warnings` at startup; at run time that service is
|
|
1017
|
+
reported once through `onWarning` and skipped, and the others keep working.
|
|
1012
1018
|
|
|
1013
1019
|
```js
|
|
1014
1020
|
const { readAiConfigFromEnv, createConfiguredRouter } = require('@astratra/ai');
|
|
@@ -1056,7 +1062,9 @@ and native voice primitives remain in `@astratra/rag` and `@astratra/voice`.
|
|
|
1056
1062
|
const { readAiConfigFromEnv, createTranscriptionService,
|
|
1057
1063
|
createSpeechService, createServiceLanguageDetector } = require('@astratra/ai');
|
|
1058
1064
|
const config = readAiConfigFromEnv({ prefix: 'IA_' });
|
|
1059
|
-
const
|
|
1065
|
+
for (const warning of config.warnings) console.warn(warning);
|
|
1066
|
+
const transcription = createTranscriptionService({ ...config.voice, localModels: config.localModels,
|
|
1067
|
+
onWarning: (message) => console.warn(message) });
|
|
1060
1068
|
const heard = await transcription.transcribe({
|
|
1061
1069
|
audio: pcm16Bytes, format: 'pcm16', language: 'fr', vocabulary: '', signal,
|
|
1062
1070
|
allowRemote: false // optional: confidential calls remain on this machine
|
|
@@ -1069,8 +1077,12 @@ const language = createServiceLanguageDetector(config.language);
|
|
|
1069
1077
|
await language.reply('hello', 'fr'); // fastText first, then small-word heuristic
|
|
1070
1078
|
```
|
|
1071
1079
|
|
|
1072
|
-
Transcription
|
|
1073
|
-
|
|
1080
|
+
Transcription follows your `transcriptionOrder` (`IA_TRANSCRIPTION_ORDER`) among
|
|
1081
|
+
the usable services: the local server, Groq (multipart with a WAV file for PCM)
|
|
1082
|
+
and Cloudflare (raw file base64 in `{ audio }`, including `success:false` checks).
|
|
1083
|
+
A single usable service needs no order; with several and no order, the call fails
|
|
1084
|
+
with `AI_TRANSCRIPTION_ORDER_REQUIRED` (`error.services` lists them). Services
|
|
1085
|
+
left out of the order are never called. Groq and Cloudflare need `models`.
|
|
1074
1086
|
`format: 'pcm16'` is little-endian 16kHz mono; `'wav'` can use the local server
|
|
1075
1087
|
when it contains that same PCM format. `'file'` forwards compressed audio to
|
|
1076
1088
|
remote services; this client does not transcode it. Base64 or byte input works.
|
|
@@ -1080,9 +1092,12 @@ stock subtitle hallucinations or repeated words are rejected; `stockPhrases`,
|
|
|
1080
1092
|
`null` if the service did not identify it. Limits, timeouts, key rotation and
|
|
1081
1093
|
rests are enforced, and an aborted request never proceeds to the next provider.
|
|
1082
1094
|
|
|
1083
|
-
Speech
|
|
1084
|
-
(
|
|
1085
|
-
|
|
1095
|
+
Speech follows your `speechOrder` (`IA_SPEECH_ORDER`, or `order`) between Gemini
|
|
1096
|
+
TTS (online, rotating keys/models, needs `models` and `voice`) and Piper `/tts`
|
|
1097
|
+
(`{ text, lang }` → validated WAV). The same rules apply: one usable service needs
|
|
1098
|
+
no order, several need one (`AI_SPEECH_ORDER_REQUIRED`). `allowRemote: false`
|
|
1099
|
+
keeps everything local. `fallback` is true when the service that answered is not
|
|
1100
|
+
first in your order. Gemini PCM is wrapped in a WAV header with the supplied
|
|
1086
1101
|
sample rate (24kHz by default), never mislabeled as an existing WAV file.
|
|
1087
1102
|
`speakableText` removes markup/emoji and limits text to 6000 characters;
|
|
1088
1103
|
`prepareText` can provide your app's pronunciation rules. A missing Piper
|
|
@@ -1092,7 +1107,8 @@ synthesis uses one provider. Native segmentation, prosody, AAC finishing and
|
|
|
1092
1107
|
voice caching are separate existing `@astratra/voice` primitives.
|
|
1093
1108
|
|
|
1094
1109
|
`AI_TRANSCRIPTION_UNAVAILABLE` and `AI_SPEECH_UNAVAILABLE` identify exhausted
|
|
1095
|
-
chains
|
|
1110
|
+
chains (`error.missing` names the settings of services skipped for lack of a
|
|
1111
|
+
model or voice); input errors use `AI_AUDIO_INPUT`/`AI_SPEECH_INPUT`. Unconfigured optional
|
|
1096
1112
|
services never initiate an implicit local request. Language supports fr/en/es
|
|
1097
1113
|
by default; custom word lists can extend it. Statistical confidence defaults to
|
|
1098
1114
|
0.5, or 0.9 for fewer than three words; unsupported/uncertain results keep the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/ai",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.1",
|
|
4
4
|
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra, plus agent guards (@astratra/ai/guards): outbound masking, prompt-injection handling for untrusted tool results, reply checks.",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=22"
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
},
|
|
38
38
|
"dependencies": {
|
|
39
39
|
"@astratra/core": "^1.0.0",
|
|
40
|
-
"@
|
|
40
|
+
"@astratra/mcp": "^1.0.0"
|
|
41
41
|
},
|
|
42
42
|
"peerDependencies": {
|
|
43
43
|
"@astratra/rag": ">=1.0.0",
|
package/src/aiConfig.js
CHANGED
|
@@ -19,6 +19,17 @@ function readAiConfigFromEnv({ env = process.env, prefix = 'IA_' } = {}) {
|
|
|
19
19
|
if (!['true', 'false', '1', '0'].includes(read(name))) throw new TypeError(`INVALID_AI_CONFIG_${name}`);
|
|
20
20
|
return ['true', '1'].includes(read(name));
|
|
21
21
|
};
|
|
22
|
+
const list = (name) => {
|
|
23
|
+
const value = json(name, []);
|
|
24
|
+
if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry.trim())) throw new TypeError(`INVALID_AI_CONFIG_${name}`);
|
|
25
|
+
return value;
|
|
26
|
+
};
|
|
27
|
+
const order = (name, known) => {
|
|
28
|
+
const value = json(name, undefined);
|
|
29
|
+
if (value === undefined) return undefined;
|
|
30
|
+
if (!Array.isArray(value) || !value.length || value.some((entry) => !known.includes(entry))) throw new TypeError(`INVALID_AI_CONFIG_${name}`);
|
|
31
|
+
return value;
|
|
32
|
+
};
|
|
22
33
|
const providers = json('PROVIDERS', []);
|
|
23
34
|
if (!Array.isArray(providers)) throw new TypeError('INVALID_AI_CONFIG_PROVIDERS');
|
|
24
35
|
const usages = {};
|
|
@@ -52,17 +63,39 @@ function readAiConfigFromEnv({ env = process.env, prefix = 'IA_' } = {}) {
|
|
|
52
63
|
reserveVision: boolean('RESERVE_VISION', false),
|
|
53
64
|
localModels: { baseUrl: read('MODELS_URL'), tokenFile: read('MODELS_TOKEN_FILE') },
|
|
54
65
|
language: { baseUrl: read('LANGUAGE_URL'), timeoutMs: number('LANGUAGE_TIMEOUT_MS', 800) },
|
|
66
|
+
// No model, voice or service order is chosen for the person: each comes
|
|
67
|
+
// from the configuration. Official service addresses are only addresses.
|
|
55
68
|
voice: {
|
|
56
69
|
piper: { baseUrl: read('TTS_URL'), tokenFile: read('TTS_TOKEN_FILE') },
|
|
57
|
-
groq: { url: read('GROQ_WHISPER_URL') || 'https://api.groq.com/openai/v1/audio/transcriptions', keys: () => readEnvironmentKeys(env, prefix + 'GROQ_KEY'), models:
|
|
58
|
-
cloudflare: { url: read('CLOUDFLARE_WHISPER_URL') || (read('CLOUDFLARE_ACCOUNT_ID')
|
|
59
|
-
gemini: { endpoint: read('GEMINI_TTS_ENDPOINT'), keys: () => readEnvironmentKeys(env, prefix + 'GEMINI_KEY'), models:
|
|
70
|
+
groq: { url: read('GROQ_WHISPER_URL') || 'https://api.groq.com/openai/v1/audio/transcriptions', keys: () => readEnvironmentKeys(env, prefix + 'GROQ_KEY'), models: list('GROQ_WHISPER_MODELS') },
|
|
71
|
+
cloudflare: { url: read('CLOUDFLARE_WHISPER_URL') || cloudflareRunUrl(read('CLOUDFLARE_ACCOUNT_ID')), keys: () => readEnvironmentKeys(env, prefix + 'CLOUDFLARE_KEY'), models: list('CLOUDFLARE_WHISPER_MODELS') },
|
|
72
|
+
gemini: { endpoint: read('GEMINI_TTS_ENDPOINT'), keys: () => readEnvironmentKeys(env, prefix + 'GEMINI_KEY'), models: list('GEMINI_TTS_MODELS'), voice: read('GEMINI_TTS_VOICE') || undefined },
|
|
73
|
+
transcriptionOrder: order('TRANSCRIPTION_ORDER', ['local', 'groq', 'cloudflare']),
|
|
74
|
+
speechOrder: order('SPEECH_ORDER', ['gemini', 'piper'])
|
|
60
75
|
}
|
|
61
76
|
};
|
|
77
|
+
config.warnings = voiceWarnings(config.voice, env, prefix);
|
|
62
78
|
if (!['skip', 'try'].includes(config.whenAllCooling)) throw new TypeError('INVALID_AI_CONFIG_WHEN_ALL_COOLING');
|
|
63
79
|
return config;
|
|
64
80
|
}
|
|
65
81
|
|
|
82
|
+
// The Workers AI run address of the account; the model is the person's.
|
|
83
|
+
function cloudflareRunUrl(accountId) {
|
|
84
|
+
if (!accountId) return undefined;
|
|
85
|
+
return (model) => `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/run/${model}`;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// A key without the settings it needs: said at startup, the service is skipped.
|
|
89
|
+
function voiceWarnings(voice, env, prefix) {
|
|
90
|
+
const warnings = [];
|
|
91
|
+
const hasKey = (name) => readEnvironmentKeys(env, prefix + name).length > 0;
|
|
92
|
+
if (hasKey('GROQ_KEY') && !voice.groq.models.length) warnings.push(`${prefix}GROQ_KEY is set but ${prefix}GROQ_WHISPER_MODELS is empty: Groq transcription is skipped.`);
|
|
93
|
+
if (hasKey('CLOUDFLARE_KEY') && voice.cloudflare.url && !voice.cloudflare.models.length) warnings.push(`${prefix}CLOUDFLARE_KEY is set but ${prefix}CLOUDFLARE_WHISPER_MODELS is empty: Cloudflare transcription is skipped.`);
|
|
94
|
+
if (hasKey('GEMINI_KEY') && !voice.gemini.models.length) warnings.push(`${prefix}GEMINI_KEY is set but ${prefix}GEMINI_TTS_MODELS is empty: Gemini speech is skipped.`);
|
|
95
|
+
if (hasKey('GEMINI_KEY') && !voice.gemini.voice) warnings.push(`${prefix}GEMINI_KEY is set but ${prefix}GEMINI_TTS_VOICE is empty: Gemini speech is skipped.`);
|
|
96
|
+
return warnings;
|
|
97
|
+
}
|
|
98
|
+
|
|
66
99
|
function readEnvironmentKeys(env, name) {
|
|
67
100
|
// Sparse suffixes work as well; a missing _2 must not hide _3.
|
|
68
101
|
const names = Object.keys(env).filter((key) => key === name || (key.startsWith(name + '_') && /^\d+$/.test(key.slice(name.length + 1))))
|
package/src/index.d.ts
CHANGED
|
@@ -605,7 +605,7 @@ export interface ChatToolCall {
|
|
|
605
605
|
export type FetchLike = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; json(): Promise<any> }>;
|
|
606
606
|
|
|
607
607
|
export function askChatModel(
|
|
608
|
-
/** `thoughtSignatures` : renvoyer les signatures de pensée de Gemini 3 (par défaut : seulement vers *.googleapis.com ; true pour
|
|
608
|
+
/** `thoughtSignatures` : renvoyer les signatures de pensée de Gemini 3 (par défaut : seulement vers *.googleapis.com ; true pour une passerelle qui les relaie). */
|
|
609
609
|
target: { url: string; key: string; model: string; extra?: Record<string, unknown>; thoughtSignatures?: boolean },
|
|
610
610
|
request: { system?: string; messages: ChatMessage[]; tools?: Array<Record<string, unknown>>; maxTokens?: number; temperature?: number },
|
|
611
611
|
io: { fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number; onText?: (shown: string) => void }
|
|
@@ -695,7 +695,7 @@ export function createOpenAICompatibleProvider(options: ChatProviderOptions & {
|
|
|
695
695
|
url: string | ((ctx: Record<string, unknown>) => string | null | undefined);
|
|
696
696
|
external?: boolean;
|
|
697
697
|
extra?: Record<string, unknown>;
|
|
698
|
-
/** Renvoyer les signatures de pensée de Gemini 3 (par défaut : seulement vers *.googleapis.com ; true pour
|
|
698
|
+
/** Renvoyer les signatures de pensée de Gemini 3 (par défaut : seulement vers *.googleapis.com ; true pour une passerelle qui les relaie). */
|
|
699
699
|
thoughtSignatures?: boolean;
|
|
700
700
|
}): Provider;
|
|
701
701
|
|
|
@@ -1015,7 +1015,10 @@ export function readEnvironmentKeys(env: Record<string, string | undefined>, nam
|
|
|
1015
1015
|
export interface AiEnvironmentConfig extends ConfiguredRouterConfig {
|
|
1016
1016
|
localModels: LocalModelsOptions;
|
|
1017
1017
|
language: ServiceLanguageOptions;
|
|
1018
|
+
/** No model, voice or order is chosen for you: empty lists and undefined until configured. */
|
|
1018
1019
|
voice: SpeechServiceOptions & TranscriptionServiceOptions;
|
|
1020
|
+
/** A key set without the model or voice its service needs; that service is skipped. */
|
|
1021
|
+
warnings: string[];
|
|
1019
1022
|
}
|
|
1020
1023
|
export function readAiConfigFromEnv(options?: { env?: Record<string, string | undefined>; prefix?: string }): AiEnvironmentConfig;
|
|
1021
1024
|
|
|
@@ -1024,6 +1027,10 @@ export class AiServiceError extends Error {
|
|
|
1024
1027
|
code: string;
|
|
1025
1028
|
status: number | null;
|
|
1026
1029
|
statusCode: number | null;
|
|
1030
|
+
/** Exhausted voice chains and AI_*_ORDER_REQUIRED: the settings to give (environment names). */
|
|
1031
|
+
missing?: string[];
|
|
1032
|
+
/** AI_*_ORDER_REQUIRED: the usable services to put in order. */
|
|
1033
|
+
services?: string[];
|
|
1027
1034
|
}
|
|
1028
1035
|
export type ServiceFetch = (url: string, init: RequestInit) => Promise<Pick<Response, 'ok' | 'status' | 'json' | 'arrayBuffer'>>;
|
|
1029
1036
|
export function createTokenFileReader(options?: {
|
|
@@ -1093,11 +1100,26 @@ export function createServiceLanguageDetector(options?: ServiceLanguageOptions):
|
|
|
1093
1100
|
|
|
1094
1101
|
export interface VoiceProviderOptions {
|
|
1095
1102
|
keys?: string[] | string | (() => Awaitable<string[] | string | undefined | null>);
|
|
1103
|
+
/** Required: no model is chosen by the package. A service with keys but no model is skipped with a warning. */
|
|
1096
1104
|
models?: string[];
|
|
1097
1105
|
timeoutMs?: number;
|
|
1098
1106
|
cooldownMs?: number;
|
|
1099
1107
|
}
|
|
1108
|
+
/** A service with keys but a missing setting: reported once, then skipped. */
|
|
1109
|
+
export interface VoiceWarning {
|
|
1110
|
+
service: 'groq' | 'cloudflare' | 'gemini';
|
|
1111
|
+
/** Environment names of the missing settings (IA_GROQ_WHISPER_MODELS…). */
|
|
1112
|
+
missing: string[];
|
|
1113
|
+
message: string;
|
|
1114
|
+
}
|
|
1100
1115
|
export interface TranscriptionServiceOptions {
|
|
1116
|
+
/**
|
|
1117
|
+
* Order of the transcription services, chosen by you. Required when several
|
|
1118
|
+
* services are usable; a single usable service needs none. Services left out
|
|
1119
|
+
* are never called.
|
|
1120
|
+
*/
|
|
1121
|
+
transcriptionOrder?: Array<'local' | 'groq' | 'cloudflare'>;
|
|
1122
|
+
onWarning?: (message: string, warning: VoiceWarning) => void;
|
|
1101
1123
|
local?: Pick<LocalModelsClient, 'transcrire'>;
|
|
1102
1124
|
localModels?: LocalModelsOptions;
|
|
1103
1125
|
localTimeoutMs?: number;
|
|
@@ -1125,15 +1147,23 @@ export interface TranscriptionResult {
|
|
|
1125
1147
|
text: string;
|
|
1126
1148
|
language: string | null;
|
|
1127
1149
|
provider: 'local' | 'groq' | 'cloudflare';
|
|
1128
|
-
model
|
|
1150
|
+
/** The model that answered; null for the local server, which does not say. */
|
|
1151
|
+
model: string | null;
|
|
1152
|
+
/** True when the service is not first in your order. */
|
|
1129
1153
|
fallback: boolean;
|
|
1130
1154
|
confidence?: number;
|
|
1131
1155
|
noSpeech?: boolean;
|
|
1132
1156
|
}
|
|
1133
1157
|
export function createTranscriptionService(options?: TranscriptionServiceOptions): { transcribe(input: TranscriptionInput): Promise<TranscriptionResult> };
|
|
1134
1158
|
export interface SpeechServiceOptions {
|
|
1135
|
-
/**
|
|
1159
|
+
/**
|
|
1160
|
+
* Order of the speech services, chosen by you. Required when several services
|
|
1161
|
+
* are usable; a single usable service needs none.
|
|
1162
|
+
*/
|
|
1163
|
+
speechOrder?: Array<'gemini' | 'piper'>;
|
|
1164
|
+
/** Same as speechOrder (kept from 1.x). */
|
|
1136
1165
|
order?: Array<'gemini' | 'piper'>;
|
|
1166
|
+
onWarning?: (message: string, warning: VoiceWarning) => void;
|
|
1137
1167
|
piper?: {
|
|
1138
1168
|
baseUrl?: string;
|
|
1139
1169
|
tokenFile?: string;
|
|
@@ -1141,6 +1171,7 @@ export interface SpeechServiceOptions {
|
|
|
1141
1171
|
timeoutMs?: number;
|
|
1142
1172
|
cooldownMs?: number;
|
|
1143
1173
|
};
|
|
1174
|
+
/** Gemini needs models and a voice, both yours; without them it is skipped with a warning. */
|
|
1144
1175
|
gemini?: VoiceProviderOptions & { endpoint?: string; voice?: string };
|
|
1145
1176
|
now?: () => number;
|
|
1146
1177
|
fetch?: ServiceFetch;
|
package/src/mcpClient.js
CHANGED
|
@@ -35,11 +35,7 @@ function resultValue(result, max) {
|
|
|
35
35
|
try { return JSON.parse(texte); } catch { return texte; }
|
|
36
36
|
}
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
|
|
40
|
-
const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
|
|
41
|
-
return { Client, StreamableHTTPClientTransport };
|
|
42
|
-
}
|
|
38
|
+
const { createMcpClient, createStreamableHttpClientTransport } = require('@astratra/mcp');
|
|
43
39
|
|
|
44
40
|
/**
|
|
45
41
|
* Se connecte à un serveur MCP et rend ses outils au format des outils natifs.
|
|
@@ -60,21 +56,13 @@ async function chargerSdk() {
|
|
|
60
56
|
async function connectMcpServer(options = {}) {
|
|
61
57
|
const { url, headers = {}, prefix = '', allow = null, kinds = {}, timeoutMs = DEFAULT_TIMEOUT_MS, resultMax = DEFAULT_RESULT_MAX } = options;
|
|
62
58
|
if (!options.transport && !url) throw new Error('connectMcpServer: url is required');
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
});
|
|
68
|
-
const client = new Client(options.client || { name: 'astratra-ai', version: '1.0.0' });
|
|
59
|
+
// Le client de @astratra/mcp : https:// seulement (http:// vers la machine), aucune redirection suivie, réponses
|
|
60
|
+
// plafonnées. Un transport du SDK officiel peut aussi être donné dans options.transport.
|
|
61
|
+
const transport = options.transport || createStreamableHttpClientTransport(url, { headers, ...(options.fetch ? { fetch: options.fetch } : {}) });
|
|
62
|
+
const client = createMcpClient(options.client || { name: 'astratra-ai', version: '1.0.0' }, { timeoutMs });
|
|
69
63
|
await client.connect(transport);
|
|
70
64
|
|
|
71
|
-
const decrits =
|
|
72
|
-
let curseur;
|
|
73
|
-
do {
|
|
74
|
-
const page = await client.listTools(curseur ? { cursor: curseur } : {});
|
|
75
|
-
decrits.push(...(page.tools || []));
|
|
76
|
-
curseur = page.nextCursor;
|
|
77
|
-
} while (curseur);
|
|
65
|
+
const decrits = await client.listAllTools();
|
|
78
66
|
|
|
79
67
|
const permis = allow ? new Set(allow) : null;
|
|
80
68
|
const tools = decrits
|
|
@@ -94,8 +82,8 @@ async function connectMcpServer(options = {}) {
|
|
|
94
82
|
mcp: { name: t.name },
|
|
95
83
|
summary: () => ({}),
|
|
96
84
|
async run(args, ctx = {}) {
|
|
97
|
-
const result = await client.callTool({ name: t.name, arguments: args || {} },
|
|
98
|
-
|
|
85
|
+
const result = await client.callTool({ name: t.name, arguments: args || {} }, {
|
|
86
|
+
timeoutMs,
|
|
99
87
|
...(ctx.signal ? { signal: ctx.signal } : {})
|
|
100
88
|
});
|
|
101
89
|
const data = resultValue(result, resultMax);
|
|
@@ -106,7 +94,7 @@ async function connectMcpServer(options = {}) {
|
|
|
106
94
|
})
|
|
107
95
|
.filter(Boolean);
|
|
108
96
|
|
|
109
|
-
const instructions =
|
|
97
|
+
const instructions = client.getInstructions() || null;
|
|
110
98
|
return {
|
|
111
99
|
tools,
|
|
112
100
|
instructions,
|
package/src/openaiCompatible.js
CHANGED
|
@@ -18,7 +18,7 @@ const { providerResult, readToolArguments, readWrittenAnswer, readWrittenToolCal
|
|
|
18
18
|
const { readServerEvents, textReporter } = require('./streamedAnswer');
|
|
19
19
|
|
|
20
20
|
/* Les signatures de pensée de Gemini 3 voyagent dans `extra_content.google.thought_signature`, une extension de Google :
|
|
21
|
-
envoyées à Google, ou à une cible qui les demande (`thoughtSignatures: true`,
|
|
21
|
+
envoyées à Google, ou à une cible qui les demande (`thoughtSignatures: true`, une passerelle qui les relaie), jamais ailleurs. */
|
|
22
22
|
const signatureOf = (call) => {
|
|
23
23
|
const signature = call && call.extra_content && call.extra_content.google && call.extra_content.google.thought_signature;
|
|
24
24
|
return typeof signature === 'string' && signature ? signature : undefined;
|
|
@@ -167,7 +167,7 @@ async function readChatStream(response, report) {
|
|
|
167
167
|
* included, for the router's `accepts` to judge) instead of the text alone.
|
|
168
168
|
* @param {Function} [options.toRequest] (prompt, ctx) => { system?, messages, tools?, maxTokens? }. Default: the prompt as one user message.
|
|
169
169
|
* @param {boolean} [options.thoughtSignatures] send the thought signatures of Gemini 3 back (default: only to *.googleapis.com);
|
|
170
|
-
* true for a gateway that relays them
|
|
170
|
+
* true for a gateway that relays them.
|
|
171
171
|
*/
|
|
172
172
|
function createOpenAICompatibleProvider(options = {}) {
|
|
173
173
|
if (typeof options.id !== 'string' || !options.id) throw new Error('createOpenAICompatibleProvider requires options.id.');
|
package/src/voice.js
CHANGED
|
@@ -46,16 +46,24 @@ function doubtfulTranscription(text, { stockPhrases = WHISPER_STOCK_PHRASES } =
|
|
|
46
46
|
return false;
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
+
async function readKeys(config = {}) {
|
|
50
|
+
const source = typeof config.keys === 'function' ? await config.keys() : config.keys;
|
|
51
|
+
return [...new Set((Array.isArray(source) ? source : [source]).filter((key) => typeof key === 'string' && key.trim()))];
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const modelsOf = (config = {}) => (Array.isArray(config.models) ? config.models.filter((model) => typeof model === 'string' && model.trim()) : []);
|
|
55
|
+
|
|
56
|
+
/* No model, voice or service order is chosen here: everything comes from the
|
|
57
|
+
caller's configuration. */
|
|
49
58
|
function rotatingPool(config = {}, now) {
|
|
50
59
|
const rests = new Map();
|
|
51
60
|
let next = 0;
|
|
52
61
|
return {
|
|
53
|
-
async candidates(
|
|
54
|
-
const
|
|
55
|
-
const keys = [...new Set((Array.isArray(source) ? source : [source]).filter(Boolean))];
|
|
62
|
+
async candidates() {
|
|
63
|
+
const keys = await readKeys(config);
|
|
56
64
|
const start = keys.length ? next++ % keys.length : 0;
|
|
57
65
|
const list = [];
|
|
58
|
-
for (const model of config
|
|
66
|
+
for (const model of modelsOf(config)) for (let offset = 0; offset < keys.length; offset += 1) {
|
|
59
67
|
const slot = (start + offset) % keys.length;
|
|
60
68
|
const id = `${model}:key-${slot + 1}`;
|
|
61
69
|
if ((rests.get(id) || 0) <= now()) list.push({ model, key: keys[slot], id });
|
|
@@ -66,6 +74,41 @@ function rotatingPool(config = {}, now) {
|
|
|
66
74
|
};
|
|
67
75
|
}
|
|
68
76
|
|
|
77
|
+
/* Each enabled service (address, key) that lacks a setting is reported once
|
|
78
|
+
through onWarning and skipped; the others keep working. */
|
|
79
|
+
function createWarner(onWarning) {
|
|
80
|
+
const said = new Set();
|
|
81
|
+
return (problem) => {
|
|
82
|
+
if (said.has(problem.message) || typeof onWarning !== 'function') return;
|
|
83
|
+
said.add(problem.message);
|
|
84
|
+
try { onWarning(problem.message, problem); } catch { /* A warning must not break a call. */ }
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function checkOrder(order, known, name) {
|
|
89
|
+
if (order === undefined || order === null) return null;
|
|
90
|
+
if (!Array.isArray(order) || order.some((service) => !known.includes(service))) throw new TypeError(`INVALID_AI_VOICE_${name}`);
|
|
91
|
+
return order;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/* The chain is the caller's order, kept to the usable services. Without an
|
|
95
|
+
order, a single usable service is used alone; several need an order. A
|
|
96
|
+
result is a fallback when its service is not first in the caller's order. */
|
|
97
|
+
function chainOf(order, usable, code, setting) {
|
|
98
|
+
if (order) return order.filter((service) => usable.includes(service));
|
|
99
|
+
if (usable.length <= 1) return usable;
|
|
100
|
+
const error = new AiServiceError(code);
|
|
101
|
+
error.missing = [setting];
|
|
102
|
+
error.services = usable;
|
|
103
|
+
throw error;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function unavailable(code, problems) {
|
|
107
|
+
const error = new AiServiceError(code);
|
|
108
|
+
error.missing = [...new Set(problems.flatMap((problem) => problem.missing))];
|
|
109
|
+
return error;
|
|
110
|
+
}
|
|
111
|
+
|
|
69
112
|
function createTranscriptionService(options = {}) {
|
|
70
113
|
const local = options.local || createLocalModelsClient({ fetch: options.fetch, ...(options.localModels || {}) });
|
|
71
114
|
const now = options.now || Date.now;
|
|
@@ -74,6 +117,22 @@ function createTranscriptionService(options = {}) {
|
|
|
74
117
|
const groqPool = rotatingPool(groq, now);
|
|
75
118
|
const cloudPool = rotatingPool(cloudflare, now);
|
|
76
119
|
const fetchImpl = options.fetch || globalThis.fetch;
|
|
120
|
+
const order = checkOrder(options.transcriptionOrder, ['local', 'groq', 'cloudflare'], 'TRANSCRIPTION_ORDER');
|
|
121
|
+
const warn = createWarner(options.onWarning);
|
|
122
|
+
const localEnabled = Boolean(options.local || options.localModels?.baseUrl);
|
|
123
|
+
async function services(allowRemote) {
|
|
124
|
+
const usable = localEnabled ? ['local'] : [];
|
|
125
|
+
const problems = [];
|
|
126
|
+
if (allowRemote) {
|
|
127
|
+
for (const [name, config, label, setting] of [['groq', groq, 'Groq', 'IA_GROQ_WHISPER_MODELS'], ['cloudflare', cloudflare, 'Cloudflare', 'IA_CLOUDFLARE_WHISPER_MODELS']]) {
|
|
128
|
+
if (!config.url || !(await readKeys(config)).length) continue;
|
|
129
|
+
if (modelsOf(config).length) { usable.push(name); continue; }
|
|
130
|
+
problems.push({ service: name, missing: [setting], message: `${label} transcription has a key but no model: set ${name}.models (${setting}). ${label} is skipped.` });
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
problems.forEach(warn);
|
|
134
|
+
return { usable, problems };
|
|
135
|
+
}
|
|
77
136
|
async function transcribe({ audio, format = 'pcm16', language = 'fr', vocabulary = '', filename = 'audio.wav', mimeType = 'audio/wav', signal, allowRemote = true } = {}) {
|
|
78
137
|
const bytes = typeof audio === 'string' ? Buffer.from(audio, 'base64') : Buffer.from(audio || []);
|
|
79
138
|
if (!bytes.length || bytes.length > (options.maxAudioBytes ?? 25000000)) throw new AiServiceError('AI_AUDIO_INPUT');
|
|
@@ -89,18 +148,29 @@ function createTranscriptionService(options = {}) {
|
|
|
89
148
|
if (wave.sampleRate === 16000 && wave.channels === 1 && validPcmAudio(wave.pcm.toString('base64'))) pcm = wave.pcm;
|
|
90
149
|
} else if (format !== 'file') throw new AiServiceError('AI_AUDIO_INPUT');
|
|
91
150
|
if (signal?.aborted) throw signal.reason;
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
}
|
|
151
|
+
const { usable, problems } = await services(allowRemote);
|
|
152
|
+
const chain = chainOf(order, usable, 'AI_TRANSCRIPTION_ORDER_REQUIRED', 'transcriptionOrder (IA_TRANSCRIPTION_ORDER)');
|
|
153
|
+
for (const [rank, service] of chain.entries()) {
|
|
154
|
+
if (signal?.aborted) throw signal.reason;
|
|
155
|
+
const result = service === 'local' ? await viaLocal(pcm, language, vocabulary, signal)
|
|
156
|
+
: service === 'groq' ? await viaGroq(file, filename, mimeType, language, vocabulary, signal)
|
|
157
|
+
: await viaCloudflare(file, signal);
|
|
158
|
+
if (result) return { ...result, fallback: (order ? order.indexOf(service) : rank) > 0 };
|
|
100
159
|
}
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
160
|
+
throw unavailable('AI_TRANSCRIPTION_UNAVAILABLE', problems);
|
|
161
|
+
}
|
|
162
|
+
async function viaLocal(pcm, language, vocabulary, signal) {
|
|
163
|
+
if (!pcm) return null;
|
|
164
|
+
const result = await local.transcrire(pcm.toString('base64'), { langue: language, vocabulaire: vocabulary, timeoutMs: options.localTimeoutMs ?? 15000, signal });
|
|
165
|
+
if (!result) return null;
|
|
166
|
+
// Genuine silence is an answer, not an outage to send to another model.
|
|
167
|
+
const silence = result.sansParole > (options.noSpeechThreshold ?? 0.6);
|
|
168
|
+
const doubtful = result.logprob < (options.logprobThreshold ?? -1) || doubtfulTranscription(result.texte, options);
|
|
169
|
+
if (silence || !doubtful) return { text: silence ? '' : result.texte, language: result.langue, provider: 'local', model: result.modele ?? null, confidence: Math.exp(Math.min(0, result.logprob)), noSpeech: silence };
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
async function viaGroq(file, filename, mimeType, language, vocabulary, signal) {
|
|
173
|
+
for (const candidate of await groqPool.candidates()) {
|
|
104
174
|
try {
|
|
105
175
|
const form = new globalThis.FormData();
|
|
106
176
|
form.set('file', new globalThis.Blob([file], { type: mimeType }), filename);
|
|
@@ -109,18 +179,20 @@ function createTranscriptionService(options = {}) {
|
|
|
109
179
|
if (vocabulary) form.set('prompt', vocabulary);
|
|
110
180
|
const data = await serviceRequest(groq.url, { fetch: fetchImpl, timeoutMs: groq.timeoutMs ?? 30000, signal, rawBody: form, headers: { Authorization: `Bearer ${candidate.key}` } });
|
|
111
181
|
if (typeof data?.text !== 'string' || doubtfulTranscription(data.text, options)) throw new AiServiceError('AI_SERVICE_RESPONSE');
|
|
112
|
-
return { text: data.text, language: data.language || null, provider: 'groq', model: candidate.model
|
|
182
|
+
return { text: data.text, language: data.language || null, provider: 'groq', model: candidate.model };
|
|
113
183
|
} catch (_error) { if (signal?.aborted) throw signal.reason; groqPool.rest(candidate.id); }
|
|
114
184
|
}
|
|
115
|
-
|
|
116
|
-
|
|
185
|
+
return null;
|
|
186
|
+
}
|
|
187
|
+
async function viaCloudflare(file, signal) {
|
|
188
|
+
for (const candidate of await cloudPool.candidates()) {
|
|
117
189
|
try {
|
|
118
190
|
const data = await serviceRequest(typeof cloudflare.url === 'function' ? cloudflare.url(candidate.model) : cloudflare.url, { fetch: fetchImpl, timeoutMs: cloudflare.timeoutMs ?? 30000, signal, body: { audio: file.toString('base64') }, headers: { Authorization: `Bearer ${candidate.key}` } });
|
|
119
191
|
if (data?.success === false || typeof data?.result?.text !== 'string' || doubtfulTranscription(data.result.text, options)) throw new AiServiceError('AI_SERVICE_RESPONSE');
|
|
120
|
-
return { text: data.result.text, language: data.result.language || null, provider: 'cloudflare', model: candidate.model
|
|
192
|
+
return { text: data.result.text, language: data.result.language || null, provider: 'cloudflare', model: candidate.model };
|
|
121
193
|
} catch (_error) { if (signal?.aborted) throw signal.reason; cloudPool.rest(candidate.id); }
|
|
122
194
|
}
|
|
123
|
-
|
|
195
|
+
return null;
|
|
124
196
|
}
|
|
125
197
|
return { transcribe };
|
|
126
198
|
}
|
|
@@ -133,8 +205,23 @@ function createSpeechService(options = {}) {
|
|
|
133
205
|
const pool = rotatingPool(gemini, now);
|
|
134
206
|
const fetchImpl = options.fetch || globalThis.fetch;
|
|
135
207
|
const piperRests = new Map();
|
|
136
|
-
/*
|
|
137
|
-
const order =
|
|
208
|
+
/* No order is chosen here: `speechOrder` (or `order`) is the caller's. */
|
|
209
|
+
const order = checkOrder(options.speechOrder ?? options.order, ['gemini', 'piper'], 'SPEECH_ORDER');
|
|
210
|
+
const warn = createWarner(options.onWarning);
|
|
211
|
+
async function services(allowRemote) {
|
|
212
|
+
const usable = piper.baseUrl ? ['piper'] : [];
|
|
213
|
+
const problems = [];
|
|
214
|
+
if (allowRemote && (await readKeys(gemini)).length) {
|
|
215
|
+
const missing = [];
|
|
216
|
+
if (!modelsOf(gemini).length) missing.push(['gemini.models', 'IA_GEMINI_TTS_MODELS']);
|
|
217
|
+
if (!(typeof gemini.voice === 'string' && gemini.voice.trim())) missing.push(['gemini.voice', 'IA_GEMINI_TTS_VOICE']);
|
|
218
|
+
if (missing.length) {
|
|
219
|
+
problems.push({ service: 'gemini', missing: missing.map(([, env]) => env), message: `Gemini speech has a key but no ${missing.map(([option, env]) => `${option.split('.')[1]} (${option}, ${env})`).join(' and no ')}. Gemini is skipped.` });
|
|
220
|
+
} else usable.unshift('gemini');
|
|
221
|
+
}
|
|
222
|
+
problems.forEach(warn);
|
|
223
|
+
return { usable, problems };
|
|
224
|
+
}
|
|
138
225
|
async function viaPiper(clean, language, signal) {
|
|
139
226
|
if (!piper.baseUrl || (piperRests.get(language) || 0) > now()) return null;
|
|
140
227
|
try {
|
|
@@ -145,11 +232,11 @@ function createSpeechService(options = {}) {
|
|
|
145
232
|
} catch (_error) { if (signal?.aborted) throw signal.reason; piperRests.set(language, now() + (piper.cooldownMs ?? 60000)); return null; }
|
|
146
233
|
}
|
|
147
234
|
async function viaGemini(clean, signal) {
|
|
148
|
-
for (const candidate of await pool.candidates(
|
|
235
|
+
for (const candidate of await pool.candidates()) {
|
|
149
236
|
try {
|
|
150
237
|
const data = await serviceRequest(endpoint(gemini.endpoint || 'https://generativelanguage.googleapis.com/v1beta/models', `/${candidate.model}:generateContent`), {
|
|
151
238
|
fetch: fetchImpl, signal, timeoutMs: gemini.timeoutMs ?? 45000, headers: { 'x-goog-api-key': candidate.key },
|
|
152
|
-
body: { contents: [{ role: 'user', parts: [{ text: clean }] }], generationConfig: { responseModalities: ['AUDIO'], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: gemini.voice
|
|
239
|
+
body: { contents: [{ role: 'user', parts: [{ text: clean }] }], generationConfig: { responseModalities: ['AUDIO'], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: gemini.voice } } } } }
|
|
153
240
|
});
|
|
154
241
|
const part = data?.candidates?.[0]?.content?.parts?.find((one) => one.inlineData || one.inline_data);
|
|
155
242
|
const inline = part?.inlineData || part?.inline_data;
|
|
@@ -167,13 +254,14 @@ function createSpeechService(options = {}) {
|
|
|
167
254
|
const clean = (options.prepareText || speakableText)(text);
|
|
168
255
|
if (!clean) throw new AiServiceError('AI_SPEECH_INPUT');
|
|
169
256
|
if (signal?.aborted) throw signal.reason;
|
|
170
|
-
|
|
257
|
+
const { usable, problems } = await services(allowRemote);
|
|
258
|
+
const chain = chainOf(order, usable, 'AI_SPEECH_ORDER_REQUIRED', 'speechOrder (IA_SPEECH_ORDER)');
|
|
259
|
+
for (const [rank, service] of chain.entries()) {
|
|
171
260
|
if (signal?.aborted) throw signal.reason;
|
|
172
|
-
const result =
|
|
173
|
-
|
|
174
|
-
if (result) return { ...result, fallback: rang > 0 };
|
|
261
|
+
const result = service === 'piper' ? await viaPiper(clean, language, signal) : await viaGemini(clean, signal);
|
|
262
|
+
if (result) return { ...result, fallback: (order ? order.indexOf(service) : rank) > 0 };
|
|
175
263
|
}
|
|
176
|
-
throw
|
|
264
|
+
throw unavailable('AI_SPEECH_UNAVAILABLE', problems);
|
|
177
265
|
}
|
|
178
266
|
return { synthesize };
|
|
179
267
|
}
|