@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 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 la passerelle Centrale) : **gardez
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; defaults Groq transcription endpoint and turbo/large-v3 |
1002
- | `IA_CLOUDFLARE_ACCOUNT_ID`, `IA_CLOUDFLARE_WHISPER_URL` | Account for the default Whisper run URL, or explicit full URL |
1003
- | `IA_GEMINI_TTS_ENDPOINT`, `IA_GEMINI_TTS_MODELS`, `IA_GEMINI_TTS_VOICE` | Models base URL, JSON model IDs, voice; defaults Gemini endpoint, gemini-2.5-flash-preview-tts, Aoede |
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. Endpoint/model defaults are configurable
1011
- protocol examples, not a claim that a model or free tier remains available.
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 transcription = createTranscriptionService({ ...config.voice, localModels: config.localModels });
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 tries local Whisper, then Groq (multipart with a WAV file for PCM),
1073
- then Cloudflare (raw file base64 in `{ audio }`, including `success:false` checks).
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 tries Gemini TTS first (online, rotating keys/models), then Piper `/tts`
1084
- (`{ text, lang }` → validated WAV) as the local fallback. `order: ['piper', 'gemini']`
1085
- reverses it; `allowRemote: false` keeps everything local. Gemini PCM is wrapped in a WAV header with the supplied
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; input errors use `AI_AUDIO_INPUT`/`AI_SPEECH_INPUT`. Unconfigured optional
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": "1.16.0",
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
- "@modelcontextprotocol/sdk": "^1.32.1"
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: json('GROQ_WHISPER_MODELS', ['whisper-large-v3-turbo', 'whisper-large-v3']) },
58
- cloudflare: { url: read('CLOUDFLARE_WHISPER_URL') || (read('CLOUDFLARE_ACCOUNT_ID') ? `https://api.cloudflare.com/client/v4/accounts/${read('CLOUDFLARE_ACCOUNT_ID')}/ai/run/@cf/openai/whisper-large-v3-turbo` : undefined), keys: () => readEnvironmentKeys(env, prefix + 'CLOUDFLARE_KEY') },
59
- gemini: { endpoint: read('GEMINI_TTS_ENDPOINT'), keys: () => readEnvironmentKeys(env, prefix + 'GEMINI_KEY'), models: json('GEMINI_TTS_MODELS', ['gemini-2.5-flash-preview-tts']), voice: read('GEMINI_TTS_VOICE') || 'Aoede' }
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 la passerelle Centrale). */
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 la passerelle Centrale). */
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: string;
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
- /** Synthesis order. Default: Gemini (online) first, Piper (local) as fallback. */
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
- async function chargerSdk() {
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
- const { Client, StreamableHTTPClientTransport } = await chargerSdk();
64
- const transport = options.transport || new StreamableHTTPClientTransport(new URL(url), {
65
- requestInit: { headers },
66
- ...(options.fetch ? { fetch: options.fetch } : {})
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 || {} }, undefined, {
98
- timeout: timeoutMs,
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 = typeof client.getInstructions === 'function' ? (client.getInstructions() || null) : null;
97
+ const instructions = client.getInstructions() || null;
110
98
  return {
111
99
  tools,
112
100
  instructions,
@@ -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`, la passerelle Centrale), jamais ailleurs. */
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 (Centrale).
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(defaultModels) {
54
- const source = typeof config.keys === 'function' ? await config.keys() : config.keys;
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.models || defaultModels) for (let offset = 0; offset < keys.length; offset += 1) {
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
- if (pcm) {
93
- const result = await local.transcrire(pcm.toString('base64'), { langue: language, vocabulaire: vocabulary, timeoutMs: options.localTimeoutMs ?? 15000, signal });
94
- if (result) {
95
- // Genuine silence is an answer, not an outage to send to another model.
96
- const silence = result.sansParole > (options.noSpeechThreshold ?? 0.6);
97
- const doubtful = result.logprob < (options.logprobThreshold ?? -1) || doubtfulTranscription(result.texte, options);
98
- if (silence || !doubtful) return { text: silence ? '' : result.texte, language: result.langue, provider: 'local', model: 'whisper', confidence: Math.exp(Math.min(0, result.logprob)), noSpeech: silence, fallback: false };
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
- if (!allowRemote) throw new AiServiceError('AI_TRANSCRIPTION_UNAVAILABLE');
102
- for (const candidate of await groqPool.candidates(['whisper-large-v3-turbo', 'whisper-large-v3'])) {
103
- if (!groq.url) break;
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, fallback: true };
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
- for (const candidate of await cloudPool.candidates(['@cf/openai/whisper-large-v3-turbo'])) {
116
- if (!cloudflare.url) break;
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, fallback: true };
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
- throw new AiServiceError('AI_TRANSCRIPTION_UNAVAILABLE');
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
- /* Gemini (en ligne) d'abord, Piper (local) en repli ; `options.order` permet l'inverse. */
137
- const order = Array.isArray(options.order) && options.order.length ? options.order : ['gemini', 'piper'];
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(['gemini-2.5-flash-preview-tts'])) {
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 || 'Aoede' } } } } }
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
- for (const [rang, nom] of order.entries()) {
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 = nom === 'piper' ? await viaPiper(clean, language, signal)
173
- : nom === 'gemini' && allowRemote ? await viaGemini(clean, signal) : null;
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 new AiServiceError('AI_SPEECH_UNAVAILABLE');
264
+ throw unavailable('AI_SPEECH_UNAVAILABLE', problems);
177
265
  }
178
266
  return { synthesize };
179
267
  }