@micdrop/mistral 1.2.0 → 1.4.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
@@ -1,6 +1,6 @@
1
1
  # @micdrop/mistral
2
2
 
3
- [Micdrop website](https://micdrop.dev) | [Documentation](https://micdrop.dev/docs/ai-integration/provided-integrations/mistral)
3
+ [Micdrop website](https://micdrop.dev) | [Documentation](https://micdrop.dev/docs/providers)
4
4
 
5
5
  Mistral AI implementation for [@micdrop/server](https://micdrop.dev/docs/server).
6
6
 
@@ -20,8 +20,9 @@ import { MicdropServer } from '@micdrop/server'
20
20
 
21
21
  const agent = new MistralAgent({
22
22
  apiKey: process.env.MISTRAL_API_KEY || '',
23
- model: 'ministral-8b-latest', // Default model
23
+ model: 'mistral-medium-latest', // Default model
24
24
  systemPrompt: 'You are a helpful assistant',
25
+ settings: { reasoningEffort: 'none' }, // Optional, the lowest answers soonest
25
26
  })
26
27
 
27
28
  // Use with MicdropServer
@@ -60,7 +61,7 @@ agent.answer().on('data', (chunk) => process.stdout.write(chunk))
60
61
  | `EndCall` | none | The agent decided that the call is over. |
61
62
  | `Failed` | none | The agent gave up generating an answer after its retries. |
62
63
 
63
- See the [Agent interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-agent) for the full contract.
64
+ See the [Agent interface](https://micdrop.dev/docs/agents/custom) for the full contract.
64
65
 
65
66
  ## Mistral STT (Speech-to-Text)
66
67
 
@@ -108,7 +109,7 @@ stt.transcribe(createReadStream('speech.pcm'))
108
109
  | `Transcript` | `string` | Transcription of one utterance. The text is empty when nothing was recognized. |
109
110
  | `Failed` | `Buffer[]` | Transcription gave up after its retries, with the audio chunks left pending. |
110
111
 
111
- See the [STT interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-stt) for the full contract.
112
+ See the [STT interface](https://micdrop.dev/docs/speech-to-text/custom) for the full contract.
112
113
 
113
114
  ## Mistral TTS (Text-to-Speech)
114
115
 
@@ -141,7 +142,7 @@ import { Readable } from 'stream'
141
142
 
142
143
  const tts = new MistralTTS({ apiKey: process.env.MISTRAL_API_KEY || '' })
143
144
 
144
- // Audio is raw PCM, 16 bits, 16 kHz, mono
145
+ // Audio is raw PCM, 16 bits, mono, at tts.sampleRate
145
146
  tts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))
146
147
  tts.on('Failed', (texts) => console.error('Failed:', texts))
147
148
 
@@ -150,16 +151,16 @@ tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))
150
151
 
151
152
  ### Events
152
153
 
153
- | Event | Payload | Description |
154
- | -------- | ---------- | --------------------------------------------------------------------- |
155
- | `Audio` | `Buffer` | A chunk of audio, PCM 16 bits, 16 kHz, mono, ready to be played. |
156
- | `Failed` | `string[]` | Synthesis gave up after an error, with the text that stayed unspoken. |
154
+ | Event | Payload | Description |
155
+ | -------- | ---------- | -------------------------------------------------------------------------------------- |
156
+ | `Audio` | `Buffer` | A chunk of audio, PCM 16 bits, mono, at `tts.sampleRate` (24 kHz), ready to be played. |
157
+ | `Failed` | `string[]` | Synthesis gave up after an error, with the text that stayed unspoken. |
157
158
 
158
- See the [TTS interface](https://micdrop.dev/docs/ai-integration/custom-integrations/custom-tts) for the full contract.
159
+ See the [TTS interface](https://micdrop.dev/docs/text-to-speech/custom) for the full contract.
159
160
 
160
161
  ## Documentation
161
162
 
162
- Read full [documentation of the Mistral integration for Micdrop](https://micdrop.dev/docs/ai-integration/provided-integrations/mistral) on the [website](https://micdrop.dev).
163
+ Read full [documentation of the Mistral integration for Micdrop](https://micdrop.dev/docs/providers) on the [website](https://micdrop.dev).
163
164
 
164
165
  ## License
165
166
 
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { Agent, AgentOptions, STT, SentenceTTS } from '@micdrop/server';
1
+ import { Agent, AgentOptions, MicdropModel, STT, SentenceTTS, MicdropVoice } from '@micdrop/server';
2
2
  import { ChatCompletionStreamRequest } from '@mistralai/mistralai/models/components';
3
3
  import { Writable, Readable } from 'stream';
4
4
 
@@ -11,12 +11,29 @@ interface MistralAgentOptions extends AgentOptions {
11
11
  maxSteps?: number;
12
12
  }
13
13
  declare class MistralAgent extends Agent<MistralAgentOptions> {
14
+ /**
15
+ * Lists the models that can answer a call: chat models that call tools. `reasoning` marks the ones that can reason, slower to answer when they do, each one once with its aliases.
16
+ *
17
+ * The list is fetched once and shared by every call of the process for a
18
+ * day. `refresh` fetches it again.
19
+ */
20
+ static listModels(options: {
21
+ apiKey: string;
22
+ refresh?: boolean;
23
+ }): Promise<MicdropModel[]>;
14
24
  private mistral;
15
25
  constructor(options: MistralAgentOptions);
16
- protected generateAnswer(stream: Writable, stepCount?: number, tryCount?: number): Promise<void>;
26
+ protected generateAnswer(stream: Writable, signal: AbortSignal): Promise<void>;
27
+ /**
28
+ * Runs one request, writing its text to the stream and running its tools.
29
+ *
30
+ * It throws a plain error when the request failed before producing
31
+ * anything, which can then be retried, and a {@link StepInterruptedError}
32
+ * once something was written or done.
33
+ */
34
+ private generateStep;
17
35
  private buildMessages;
18
36
  private buildTools;
19
- cancel(): void;
20
37
  }
21
38
 
22
39
  /**
@@ -30,33 +47,47 @@ interface MistralSTTOptions {
30
47
  model?: string;
31
48
  encoding?: MistralAudioEncoding;
32
49
  targetStreamingDelayMs?: number;
50
+ /** How long a connection attempt may take */
33
51
  connectionTimeout?: number;
52
+ /** How long an utterance waits for its transcript once it ended */
34
53
  transcriptionTimeout?: number;
54
+ /** Delay between two connection attempts */
35
55
  retryDelay?: number;
56
+ /** How many attempts in a row may fail before `Failed` is emitted */
36
57
  maxRetry?: number;
37
58
  }
38
59
  declare class MistralSTT extends STT {
39
60
  private options;
40
- private socket?;
41
- private initPromise;
42
- private reconnectTimeout?;
43
- private connectionTimeout?;
44
- private transcriptionTimeout?;
45
- private audioChunksPending;
46
- private transcriptDelta;
47
- private retryCount;
48
- private destroyed;
61
+ /**
62
+ * Lists the models that transcribe as the user speaks, the realtime ones `MistralSTT` streams to, each one once with its aliases.
63
+ *
64
+ * The list is fetched once and shared by every call of the process for a
65
+ * day. `refresh` fetches it again.
66
+ */
67
+ static listModels(options: {
68
+ apiKey: string;
69
+ refresh?: boolean;
70
+ }): Promise<MicdropModel[]>;
71
+ private socket;
72
+ private utterances;
73
+ private staleFlushes;
49
74
  constructor(options: MistralSTTOptions);
50
75
  transcribe(audioStream: Readable): void;
51
76
  destroy(): void;
52
- private connect;
53
77
  private getURL;
54
- private initWS;
55
- private sendSessionUpdate;
56
- private sendAudioChunk;
78
+ private getSessionUpdate;
79
+ private onOpen;
80
+ private onMessage;
81
+ private onFailed;
82
+ private endUtterance;
57
83
  private flushAudio;
58
- private handleMessage;
59
- private reconnect;
84
+ private get transcriptionTimeout();
85
+ /** Whether an answer to a timed out flush may still be on its way */
86
+ private hasStaleFlush;
87
+ private complete;
88
+ private removeUtterance;
89
+ private dropUtterance;
90
+ private sendAudioChunk;
60
91
  }
61
92
 
62
93
  /**
@@ -81,7 +112,33 @@ interface MistralTTSOptions {
81
112
  }
82
113
  declare class MistralTTS extends SentenceTTS {
83
114
  private readonly options;
115
+ /**
116
+ * Lists the models that speak, each one once with its aliases.
117
+ *
118
+ * The list is fetched once and shared by every call of the process for a
119
+ * day. `refresh` fetches it again.
120
+ */
121
+ static listModels(options: {
122
+ apiKey: string;
123
+ baseUrl?: string;
124
+ refresh?: boolean;
125
+ }): Promise<MicdropModel[]>;
126
+ /**
127
+ * Lists the voices the account can speak with, the presets and its own.
128
+ *
129
+ * `language`, such as `fr` or `fr-FR`, keeps the voices that speak it.
130
+ *
131
+ * The list is fetched once and shared by every call of the process for a
132
+ * day. `refresh` fetches it again, for a voice added a moment ago.
133
+ */
134
+ static listVoices(options: {
135
+ apiKey: string;
136
+ baseUrl?: string;
137
+ language?: string;
138
+ refresh?: boolean;
139
+ }): Promise<MicdropVoice[]>;
84
140
  constructor(options: MistralTTSOptions);
141
+ get sampleRate(): number;
85
142
  protected synthesize(text: string, signal: AbortSignal): Promise<undefined>;
86
143
  private request;
87
144
  }
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { Agent, AgentOptions, STT, SentenceTTS } from '@micdrop/server';
1
+ import { Agent, AgentOptions, MicdropModel, STT, SentenceTTS, MicdropVoice } from '@micdrop/server';
2
2
  import { ChatCompletionStreamRequest } from '@mistralai/mistralai/models/components';
3
3
  import { Writable, Readable } from 'stream';
4
4
 
@@ -11,12 +11,29 @@ interface MistralAgentOptions extends AgentOptions {
11
11
  maxSteps?: number;
12
12
  }
13
13
  declare class MistralAgent extends Agent<MistralAgentOptions> {
14
+ /**
15
+ * Lists the models that can answer a call: chat models that call tools. `reasoning` marks the ones that can reason, slower to answer when they do, each one once with its aliases.
16
+ *
17
+ * The list is fetched once and shared by every call of the process for a
18
+ * day. `refresh` fetches it again.
19
+ */
20
+ static listModels(options: {
21
+ apiKey: string;
22
+ refresh?: boolean;
23
+ }): Promise<MicdropModel[]>;
14
24
  private mistral;
15
25
  constructor(options: MistralAgentOptions);
16
- protected generateAnswer(stream: Writable, stepCount?: number, tryCount?: number): Promise<void>;
26
+ protected generateAnswer(stream: Writable, signal: AbortSignal): Promise<void>;
27
+ /**
28
+ * Runs one request, writing its text to the stream and running its tools.
29
+ *
30
+ * It throws a plain error when the request failed before producing
31
+ * anything, which can then be retried, and a {@link StepInterruptedError}
32
+ * once something was written or done.
33
+ */
34
+ private generateStep;
17
35
  private buildMessages;
18
36
  private buildTools;
19
- cancel(): void;
20
37
  }
21
38
 
22
39
  /**
@@ -30,33 +47,47 @@ interface MistralSTTOptions {
30
47
  model?: string;
31
48
  encoding?: MistralAudioEncoding;
32
49
  targetStreamingDelayMs?: number;
50
+ /** How long a connection attempt may take */
33
51
  connectionTimeout?: number;
52
+ /** How long an utterance waits for its transcript once it ended */
34
53
  transcriptionTimeout?: number;
54
+ /** Delay between two connection attempts */
35
55
  retryDelay?: number;
56
+ /** How many attempts in a row may fail before `Failed` is emitted */
36
57
  maxRetry?: number;
37
58
  }
38
59
  declare class MistralSTT extends STT {
39
60
  private options;
40
- private socket?;
41
- private initPromise;
42
- private reconnectTimeout?;
43
- private connectionTimeout?;
44
- private transcriptionTimeout?;
45
- private audioChunksPending;
46
- private transcriptDelta;
47
- private retryCount;
48
- private destroyed;
61
+ /**
62
+ * Lists the models that transcribe as the user speaks, the realtime ones `MistralSTT` streams to, each one once with its aliases.
63
+ *
64
+ * The list is fetched once and shared by every call of the process for a
65
+ * day. `refresh` fetches it again.
66
+ */
67
+ static listModels(options: {
68
+ apiKey: string;
69
+ refresh?: boolean;
70
+ }): Promise<MicdropModel[]>;
71
+ private socket;
72
+ private utterances;
73
+ private staleFlushes;
49
74
  constructor(options: MistralSTTOptions);
50
75
  transcribe(audioStream: Readable): void;
51
76
  destroy(): void;
52
- private connect;
53
77
  private getURL;
54
- private initWS;
55
- private sendSessionUpdate;
56
- private sendAudioChunk;
78
+ private getSessionUpdate;
79
+ private onOpen;
80
+ private onMessage;
81
+ private onFailed;
82
+ private endUtterance;
57
83
  private flushAudio;
58
- private handleMessage;
59
- private reconnect;
84
+ private get transcriptionTimeout();
85
+ /** Whether an answer to a timed out flush may still be on its way */
86
+ private hasStaleFlush;
87
+ private complete;
88
+ private removeUtterance;
89
+ private dropUtterance;
90
+ private sendAudioChunk;
60
91
  }
61
92
 
62
93
  /**
@@ -81,7 +112,33 @@ interface MistralTTSOptions {
81
112
  }
82
113
  declare class MistralTTS extends SentenceTTS {
83
114
  private readonly options;
115
+ /**
116
+ * Lists the models that speak, each one once with its aliases.
117
+ *
118
+ * The list is fetched once and shared by every call of the process for a
119
+ * day. `refresh` fetches it again.
120
+ */
121
+ static listModels(options: {
122
+ apiKey: string;
123
+ baseUrl?: string;
124
+ refresh?: boolean;
125
+ }): Promise<MicdropModel[]>;
126
+ /**
127
+ * Lists the voices the account can speak with, the presets and its own.
128
+ *
129
+ * `language`, such as `fr` or `fr-FR`, keeps the voices that speak it.
130
+ *
131
+ * The list is fetched once and shared by every call of the process for a
132
+ * day. `refresh` fetches it again, for a voice added a moment ago.
133
+ */
134
+ static listVoices(options: {
135
+ apiKey: string;
136
+ baseUrl?: string;
137
+ language?: string;
138
+ refresh?: boolean;
139
+ }): Promise<MicdropVoice[]>;
84
140
  constructor(options: MistralTTSOptions);
141
+ get sampleRate(): number;
85
142
  protected synthesize(text: string, signal: AbortSignal): Promise<undefined>;
86
143
  private request;
87
144
  }