@providerkit/core 0.29.1 → 0.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -4
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +29 -2
- package/dist/errors.js.map +1 -1
- package/dist/jev.d.ts +123 -0
- package/dist/jev.d.ts.map +1 -0
- package/dist/jev.js +278 -0
- package/dist/jev.js.map +1 -0
- package/dist/presets.d.ts +35 -4
- package/dist/presets.d.ts.map +1 -1
- package/dist/presets.js +32 -8
- package/dist/presets.js.map +1 -1
- package/dist/providers/deepgram-transcription.d.ts +24 -0
- package/dist/providers/deepgram-transcription.d.ts.map +1 -0
- package/dist/providers/deepgram-transcription.js +84 -0
- package/dist/providers/deepgram-transcription.js.map +1 -0
- package/dist/providers/openai-transcription.d.ts +21 -0
- package/dist/providers/openai-transcription.d.ts.map +1 -0
- package/dist/providers/openai-transcription.js +144 -0
- package/dist/providers/openai-transcription.js.map +1 -0
- package/dist/providers/transcription-factory.d.ts +30 -0
- package/dist/providers/transcription-factory.d.ts.map +1 -0
- package/dist/providers/transcription-factory.js +38 -0
- package/dist/providers/transcription-factory.js.map +1 -0
- package/dist/speech-core.d.ts +2 -17
- package/dist/speech-core.d.ts.map +1 -1
- package/dist/speech-core.js +10 -50
- package/dist/speech-core.js.map +1 -1
- package/dist/transcription-core.d.ts +146 -0
- package/dist/transcription-core.d.ts.map +1 -0
- package/dist/transcription-core.js +193 -0
- package/dist/transcription-core.js.map +1 -0
- package/dist/transcription.d.ts +7 -0
- package/dist/transcription.d.ts.map +1 -0
- package/dist/transcription.js +12 -0
- package/dist/transcription.js.map +1 -0
- package/dist/transport.d.ts +26 -0
- package/dist/transport.d.ts.map +1 -1
- package/dist/transport.js +57 -2
- package/dist/transport.js.map +1 -1
- package/package.json +5 -1
- package/src/errors.ts +35 -2
- package/src/presets.ts +54 -8
- package/src/providers/deepgram-transcription.ts +109 -0
- package/src/providers/openai-transcription.ts +177 -0
- package/src/providers/transcription-factory.ts +68 -0
- package/src/speech-core.ts +9 -47
- package/src/transcription-core.ts +345 -0
- package/src/transcription.ts +24 -0
- package/src/transport.ts +77 -3
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
// The transcription twin of `createSpeechProvider`: name a preset, hand over a key, get a
|
|
2
|
+
// transcription provider. The preset row (`ProviderPreset.transcription`) picks the wire.
|
|
3
|
+
import {
|
|
4
|
+
PROVIDER_PRESETS,
|
|
5
|
+
TRANSCRIPTION_PRESET_IDS,
|
|
6
|
+
type ProviderPreset,
|
|
7
|
+
type ProviderPresetId,
|
|
8
|
+
} from "../presets.ts";
|
|
9
|
+
import type { Attribution } from "../attribution.ts";
|
|
10
|
+
import type { TranscriptionLimits, TranscriptionProvider } from "../transcription-core.ts";
|
|
11
|
+
import { createOpenAITranscriptionProvider } from "./openai-transcription.ts";
|
|
12
|
+
import type { FetchLike } from "../transport.ts";
|
|
13
|
+
|
|
14
|
+
export interface TranscriptionProviderConfig extends TranscriptionLimits, Attribution {
|
|
15
|
+
apiKey: string;
|
|
16
|
+
/** Absent: the preset's `transcription.defaultModel`. A preset without one needs this. */
|
|
17
|
+
model?: string;
|
|
18
|
+
/**
|
|
19
|
+
* Replaces the preset's host, for a server that copies its route (Groq, a local Whisper
|
|
20
|
+
* server, a proxy). The preset's default model is a fact about its own host, so it does not
|
|
21
|
+
* follow you here: pass the `model`.
|
|
22
|
+
*/
|
|
23
|
+
baseUrl?: string;
|
|
24
|
+
headers?: Record<string, string>;
|
|
25
|
+
/** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
|
|
26
|
+
fetchImpl?: FetchLike;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Build a transcription provider for a preset that can transcribe. A preset without a
|
|
31
|
+
* `transcription` row throws, naming the ones that do (`TRANSCRIPTION_PRESET_IDS`). Deepgram is
|
|
32
|
+
* not a chat preset: `createDeepgramTranscriptionProvider` builds it.
|
|
33
|
+
*
|
|
34
|
+
* ```ts
|
|
35
|
+
* const listen = createTranscriptionProvider("openai", { apiKey });
|
|
36
|
+
* const { text } = await listen.transcribe({ audio: file });
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
export function createTranscriptionProvider(
|
|
40
|
+
id: ProviderPresetId,
|
|
41
|
+
config: TranscriptionProviderConfig,
|
|
42
|
+
): TranscriptionProvider {
|
|
43
|
+
const preset: ProviderPreset = PROVIDER_PRESETS[id];
|
|
44
|
+
const spec = preset.transcription;
|
|
45
|
+
if (!spec) {
|
|
46
|
+
throw new Error(
|
|
47
|
+
`[providerkit] Preset "${id}" has no transcription endpoint. Presets that do: ${TRANSCRIPTION_PRESET_IDS.join(", ")}. Deepgram has its own: createDeepgramTranscriptionProvider.`,
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
// A default is a fact about the host that documented it.
|
|
51
|
+
const own = config.baseUrl === undefined;
|
|
52
|
+
const model = config.model ?? (own ? spec.defaultModel : undefined);
|
|
53
|
+
if (!model) {
|
|
54
|
+
throw new Error(
|
|
55
|
+
`[providerkit] Transcription on "${id}" has no default model${own ? "" : " for another host"}. Pass a model.`,
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
const shared = {
|
|
59
|
+
...config,
|
|
60
|
+
id,
|
|
61
|
+
model,
|
|
62
|
+
baseUrl: config.baseUrl ?? spec.baseUrl ?? preset.baseUrl,
|
|
63
|
+
};
|
|
64
|
+
switch (spec.shape) {
|
|
65
|
+
case "openai":
|
|
66
|
+
return createOpenAITranscriptionProvider(shared);
|
|
67
|
+
}
|
|
68
|
+
}
|
package/src/speech-core.ts
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
// 2. Audio is named by its own bytes, not by what was asked for. Many servers ignore
|
|
11
11
|
// the format they were sent, and "WebM with an MP4 name" is not MP4.
|
|
12
12
|
import { ProviderError, streamError, type ErrorKind } from "./errors.ts";
|
|
13
|
-
import {
|
|
13
|
+
import { callOnce, noReplay as sharedNoReplay, type ErrorRebuild } from "./transport.ts";
|
|
14
14
|
import type { TokenUsage } from "./types.ts";
|
|
15
15
|
|
|
16
16
|
export const SPEECH_FORMATS = ["wav", "pcm", "mp3", "opus", "aac", "flac"] as const;
|
|
@@ -178,63 +178,25 @@ export function prepareSpeech(
|
|
|
178
178
|
return { text, voice, format };
|
|
179
179
|
}
|
|
180
180
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
"overload",
|
|
185
|
-
"unknown",
|
|
186
|
-
]);
|
|
187
|
-
|
|
188
|
-
function neverRetry(err: ProviderError): ProviderError {
|
|
189
|
-
const opts = {
|
|
190
|
-
status: err.status,
|
|
191
|
-
code: err.code,
|
|
192
|
-
retryAfterMs: err.retryAfterMs,
|
|
193
|
-
resetAtMs: err.resetAtMs,
|
|
194
|
-
window: err.window,
|
|
195
|
-
shouldRetry: false,
|
|
196
|
-
body: err.body,
|
|
197
|
-
cause: err.cause,
|
|
198
|
-
};
|
|
199
|
-
return err instanceof SpeechError
|
|
181
|
+
/** A `SpeechError` comes back as itself, with the usage it carries. */
|
|
182
|
+
const asSpeechError: ErrorRebuild = (err, opts) =>
|
|
183
|
+
err instanceof SpeechError
|
|
200
184
|
? new SpeechError(err.provider, err.kind, err.message, { ...opts, usage: err.usage })
|
|
201
185
|
: new ProviderError(err.provider, err.kind, err.message, opts);
|
|
202
|
-
}
|
|
203
186
|
|
|
204
|
-
/**
|
|
205
|
-
* @internal The "could the vendor already have billed this?" rule, applied in one
|
|
206
|
-
* place so a new failure path cannot forget it.
|
|
207
|
-
*
|
|
208
|
-
* - The caller's Stop comes back untouched.
|
|
209
|
-
* - A timeout, a dead socket, a 5xx or anything unclassified may have landed after
|
|
210
|
-
* the vendor started work, so it is marked `shouldRetry: false`, and a vendor's
|
|
211
|
-
* `x-should-retry: true` does not undo that: the header says the vendor thinks a
|
|
212
|
-
* resend is fine, not that the first call was not billed.
|
|
213
|
-
* - Every other kind keeps what it came with. A 429 means the vendor refused before
|
|
214
|
-
* doing any work, so sending it again is safe, and `Retry-After` is honoured by
|
|
215
|
-
* the caller's own retry. `x-should-retry` is believed there, in either direction.
|
|
216
|
-
*/
|
|
187
|
+
/** @internal The shared no-replay rule (`transport.ts`), keeping a `SpeechError` whole. */
|
|
217
188
|
export function noReplay(provider: string, error: unknown, signal?: AbortSignal): unknown {
|
|
218
|
-
|
|
219
|
-
const err = ProviderError.from(provider, error);
|
|
220
|
-
return REPLAY_UNSAFE.has(err.kind) && err.shouldRetry !== false ? neverRetry(err) : err;
|
|
189
|
+
return sharedNoReplay(provider, error, signal, asSpeechError);
|
|
221
190
|
}
|
|
222
191
|
|
|
223
|
-
/**
|
|
224
|
-
|
|
225
|
-
* no-replay rule applied to whatever it throws. Both wires go through here.
|
|
226
|
-
*/
|
|
227
|
-
export async function synthesizeOnce<T>(
|
|
192
|
+
/** @internal One paid call, once, under one deadline. All three wires go through here. */
|
|
193
|
+
export function synthesizeOnce<T>(
|
|
228
194
|
provider: string,
|
|
229
195
|
timeoutMs: number,
|
|
230
196
|
request: SpeechRequest,
|
|
231
197
|
call: (signal: AbortSignal) => Promise<T>,
|
|
232
198
|
): Promise<T> {
|
|
233
|
-
|
|
234
|
-
return await withDeadline(provider, timeoutMs, request.signal, call);
|
|
235
|
-
} catch (error) {
|
|
236
|
-
throw noReplay(provider, error, request.signal);
|
|
237
|
-
}
|
|
199
|
+
return callOnce(provider, timeoutMs, request.signal, call, asSpeechError);
|
|
238
200
|
}
|
|
239
201
|
|
|
240
202
|
// ── failures ──────────────────────────────────────────────────────────────
|
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
// Transcription: one recording in, its text out. The inverse of speech, and a third kind of
|
|
2
|
+
// client next to `Provider`, reached through `@providerkit/core/transcription` so a chat-only
|
|
3
|
+
// app never loads it.
|
|
4
|
+
//
|
|
5
|
+
// This file holds what both wires share: the types, the error, the checks made before a
|
|
6
|
+
// request, and the rule that a paid transcription is never replayed. A recording is billed by
|
|
7
|
+
// its length the moment the vendor starts on it, so a timeout or a dropped socket after the
|
|
8
|
+
// upload may already have cost money. One request per call (invariant 16).
|
|
9
|
+
import { ProviderError, streamError, type ErrorKind } from "./errors.ts";
|
|
10
|
+
import { callOnce, type ErrorRebuild } from "./transport.ts";
|
|
11
|
+
|
|
12
|
+
/** Which wire listens. A second shape is one new file and one preset row. */
|
|
13
|
+
export type TranscriptionShape = "openai";
|
|
14
|
+
|
|
15
|
+
export interface TranscriptionRequest {
|
|
16
|
+
/**
|
|
17
|
+
* The recording. A `File` is a `Blob`. Its `type` is required ("audio/wav", "audio/mpeg"):
|
|
18
|
+
* Deepgram reads the format from the Content-Type it becomes, OpenAI from the file name it
|
|
19
|
+
* implies. Empty, untyped or over `maxAudioBytes` is refused before any request.
|
|
20
|
+
*/
|
|
21
|
+
audio: Blob;
|
|
22
|
+
/** This call's model. Absent: the provider's. */
|
|
23
|
+
model?: string;
|
|
24
|
+
/** BCP-47, such as "pt-BR". Absent: the provider detects the language. */
|
|
25
|
+
language?: string;
|
|
26
|
+
/** Label who speaks each segment. Absent or false: no speaker labels. */
|
|
27
|
+
diarize?: boolean;
|
|
28
|
+
/** The caller's Stop. Never retried and never turned into a timeout. */
|
|
29
|
+
signal?: AbortSignal;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface TranscriptionSegment {
|
|
33
|
+
/** Seconds from the start of the recording. */
|
|
34
|
+
start: number;
|
|
35
|
+
end: number;
|
|
36
|
+
text: string;
|
|
37
|
+
/**
|
|
38
|
+
* Who spoke, as the provider labels them: Deepgram counts from 0, OpenAI sends a string.
|
|
39
|
+
* Only when `diarize` was asked for and the provider said.
|
|
40
|
+
*/
|
|
41
|
+
speaker?: number | string;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* What the provider stated it billed for, in its own unit. Never estimated. Deepgram states
|
|
46
|
+
* none: it bills by the recording's length, which is `durationSeconds`.
|
|
47
|
+
*/
|
|
48
|
+
export type TranscriptionUsage =
|
|
49
|
+
| {
|
|
50
|
+
type: "tokens";
|
|
51
|
+
inputTokens: number;
|
|
52
|
+
outputTokens: number;
|
|
53
|
+
totalTokens: number;
|
|
54
|
+
/** The parts of `inputTokens` that were audio and prompt text, when stated. */
|
|
55
|
+
audioTokens?: number;
|
|
56
|
+
textTokens?: number;
|
|
57
|
+
}
|
|
58
|
+
| { type: "duration"; seconds: number };
|
|
59
|
+
|
|
60
|
+
export interface TranscriptionResult {
|
|
61
|
+
/** The whole transcript. "" when nobody spoke. */
|
|
62
|
+
text: string;
|
|
63
|
+
/** Timed pieces of the transcript. Empty when the wire or the model gives none. */
|
|
64
|
+
segments: TranscriptionSegment[];
|
|
65
|
+
/** The recording's length in seconds, as the provider stated it. Never estimated. */
|
|
66
|
+
durationSeconds?: number;
|
|
67
|
+
/** Only when the provider reported it. */
|
|
68
|
+
usage?: TranscriptionUsage;
|
|
69
|
+
/** The model that was asked for. */
|
|
70
|
+
model: string;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export interface TranscriptionProvider {
|
|
74
|
+
readonly id: string;
|
|
75
|
+
readonly model: string;
|
|
76
|
+
/**
|
|
77
|
+
* Exactly one HTTP request. No retry, no fallback, no second key. Throws a
|
|
78
|
+
* `ProviderError`; a reply that arrived but holds no usable transcript throws a
|
|
79
|
+
* `TranscriptionError`, which keeps the usage the provider billed for it.
|
|
80
|
+
*/
|
|
81
|
+
transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export interface TranscriptionLimits {
|
|
85
|
+
/** Largest recording sent, in bytes. Default 25 MiB, OpenAI's documented limit; Deepgram's
|
|
86
|
+
* own wire defaults to its 2 GB. Over it is refused before any request. Never cut. */
|
|
87
|
+
maxAudioBytes?: number;
|
|
88
|
+
/** One deadline for the whole call: the upload, the work and the reply. Default 600,000:
|
|
89
|
+
* ten minutes, past which Deepgram itself answers 504. */
|
|
90
|
+
timeoutMs?: number;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export const DEFAULT_TRANSCRIPTION_LIMITS = {
|
|
94
|
+
maxAudioBytes: 25 * 1024 * 1024,
|
|
95
|
+
timeoutMs: 600_000,
|
|
96
|
+
} as const satisfies Required<TranscriptionLimits>;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The largest reply read. A transcript is text, and an hour of speech with every word timed is
|
|
100
|
+
* a few megabytes, so this only stops a runaway server from filling an MV3 worker's memory.
|
|
101
|
+
*/
|
|
102
|
+
export const MAX_REPLY_BYTES = 64 * 1024 * 1024;
|
|
103
|
+
|
|
104
|
+
type ProviderErrorOptions = NonNullable<ConstructorParameters<typeof ProviderError>[3]>;
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* A reply that arrived but holds no usable transcript, or a failure the provider reported
|
|
108
|
+
* inside a 200. Carries the usage the provider stated for it, because it billed that: a caller
|
|
109
|
+
* that drops this loses the only record of the charge. Plain `ProviderError`s carry no usage.
|
|
110
|
+
*/
|
|
111
|
+
export class TranscriptionError extends ProviderError {
|
|
112
|
+
readonly usage?: TranscriptionUsage;
|
|
113
|
+
|
|
114
|
+
constructor(
|
|
115
|
+
provider: string,
|
|
116
|
+
kind: ErrorKind,
|
|
117
|
+
message: string,
|
|
118
|
+
opts: ProviderErrorOptions & { usage?: TranscriptionUsage } = {},
|
|
119
|
+
) {
|
|
120
|
+
const { usage, ...rest } = opts;
|
|
121
|
+
super(provider, kind, message, rest);
|
|
122
|
+
this.name = "TranscriptionError";
|
|
123
|
+
this.usage = usage;
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** @internal Positive integers or a RangeError, at build time, never mid-call. */
|
|
128
|
+
export function resolveLimits(
|
|
129
|
+
config: TranscriptionLimits,
|
|
130
|
+
maxAudioBytes: number = DEFAULT_TRANSCRIPTION_LIMITS.maxAudioBytes,
|
|
131
|
+
): Required<TranscriptionLimits> {
|
|
132
|
+
const limits = {
|
|
133
|
+
maxAudioBytes: config.maxAudioBytes ?? maxAudioBytes,
|
|
134
|
+
timeoutMs: config.timeoutMs ?? DEFAULT_TRANSCRIPTION_LIMITS.timeoutMs,
|
|
135
|
+
};
|
|
136
|
+
for (const [name, value] of Object.entries(limits)) {
|
|
137
|
+
if (!Number.isSafeInteger(value) || value < 1) {
|
|
138
|
+
throw new RangeError(`[providerkit] ${name} must be a positive integer`);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return limits;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
const refuse = (provider: string, code: string, message: string, kind: ErrorKind = "invalid") =>
|
|
145
|
+
new ProviderError(provider, kind, `${provider}: ${message}`, { code, shouldRetry: false });
|
|
146
|
+
|
|
147
|
+
/** Space to tilde. Anything else in a header value is refused or altered by a runtime, which
|
|
148
|
+
* then quotes the value, key included, in its error. */
|
|
149
|
+
const HEADER_SAFE = /^[\x20-\x7e]*$/;
|
|
150
|
+
|
|
151
|
+
/** The media type without its parameters, lowercased: "audio/ogg; codecs=opus" is "audio/ogg". */
|
|
152
|
+
export const mediaType = (type: string) => type.split(";")[0]!.trim().toLowerCase();
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* @internal Check what the call carries and fill in its model. Throws BEFORE any request, so a
|
|
156
|
+
* recording that cannot go is never uploaded, and a refusal costs nothing.
|
|
157
|
+
*/
|
|
158
|
+
export function prepareTranscription(
|
|
159
|
+
provider: string,
|
|
160
|
+
request: TranscriptionRequest,
|
|
161
|
+
defaults: {
|
|
162
|
+
/** Checked, never echoed. */
|
|
163
|
+
apiKey: string;
|
|
164
|
+
/** Deepgram has no keyless mode; a local OpenAI-shaped server may. */
|
|
165
|
+
keyRequired: boolean;
|
|
166
|
+
model: string;
|
|
167
|
+
maxAudioBytes: number;
|
|
168
|
+
},
|
|
169
|
+
): { audio: Blob; model: string; language?: string; diarize: boolean } {
|
|
170
|
+
if (!HEADER_SAFE.test(defaults.apiKey) || (defaults.keyRequired && !defaults.apiKey)) {
|
|
171
|
+
throw refuse(
|
|
172
|
+
provider,
|
|
173
|
+
"key_invalid",
|
|
174
|
+
"the API key is empty or holds a character that cannot be sent in a header (a line break or a character outside plain ASCII). Paste the key again",
|
|
175
|
+
"auth",
|
|
176
|
+
);
|
|
177
|
+
}
|
|
178
|
+
const { audio } = request;
|
|
179
|
+
if (!(audio instanceof Blob) || audio.size === 0) {
|
|
180
|
+
throw refuse(provider, "audio_empty", "there is no audio to transcribe");
|
|
181
|
+
}
|
|
182
|
+
if (!mediaType(audio.type)) {
|
|
183
|
+
throw refuse(
|
|
184
|
+
provider,
|
|
185
|
+
"audio_type_missing",
|
|
186
|
+
'the audio has no media type. Give the Blob one, such as new Blob([bytes], { type: "audio/wav" })',
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
if (audio.size > defaults.maxAudioBytes) {
|
|
190
|
+
throw refuse(
|
|
191
|
+
provider,
|
|
192
|
+
"audio_too_large",
|
|
193
|
+
`the audio is ${audio.size} bytes and the limit is ${defaults.maxAudioBytes}`,
|
|
194
|
+
);
|
|
195
|
+
}
|
|
196
|
+
const model = (request.model ?? defaults.model ?? "").trim();
|
|
197
|
+
if (!model) throw refuse(provider, "model_required", "name a model");
|
|
198
|
+
const language = request.language?.trim();
|
|
199
|
+
return { audio, model, ...(language ? { language } : {}), diarize: request.diarize === true };
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/** A `TranscriptionError` comes back as itself, with the usage it carries. */
|
|
203
|
+
const asTranscriptionError: ErrorRebuild = (err, opts) =>
|
|
204
|
+
err instanceof TranscriptionError
|
|
205
|
+
? new TranscriptionError(err.provider, err.kind, err.message, { ...opts, usage: err.usage })
|
|
206
|
+
: new ProviderError(err.provider, err.kind, err.message, opts);
|
|
207
|
+
|
|
208
|
+
// Both vendors' words for a recording they could not read. Deepgram: "Bad Request: failed to
|
|
209
|
+
// process audio: corrupt or unsupported data". OpenAI: "Invalid file format. Supported formats:
|
|
210
|
+
// [...]" and "Audio file might be corrupted or unsupported". Read 2026-11-11.
|
|
211
|
+
const AUDIO_UNREADABLE: readonly RegExp[] = [
|
|
212
|
+
/failed to process audio/i,
|
|
213
|
+
/corrupt(?:ed)? or unsupported/i,
|
|
214
|
+
/(?:invalid|unrecognized|unsupported) file format/i,
|
|
215
|
+
/could not be decoded/i,
|
|
216
|
+
];
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* The classifier calls a refused recording `invalid`, the same as any request we got wrong.
|
|
220
|
+
* The fix is a different file, so it is named by `code`: `audio_too_large` for a 413, and
|
|
221
|
+
* `audio_invalid` when the vendor says it could not read the audio. The kind stays.
|
|
222
|
+
*/
|
|
223
|
+
function audioRefusalCode(error: ProviderError): string | undefined {
|
|
224
|
+
if (error.status === 413) return "audio_too_large";
|
|
225
|
+
if (AUDIO_UNREADABLE.some((pattern) => pattern.test(error.body ?? ""))) return "audio_invalid";
|
|
226
|
+
return undefined;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
function nameAudioRefusal(error: unknown): unknown {
|
|
230
|
+
if (!(error instanceof ProviderError) || error.kind !== "invalid" || error.code) return error;
|
|
231
|
+
const code = audioRefusalCode(error);
|
|
232
|
+
if (!code) return error;
|
|
233
|
+
return new ProviderError(error.provider, error.kind, error.message, {
|
|
234
|
+
status: error.status,
|
|
235
|
+
code,
|
|
236
|
+
shouldRetry: false,
|
|
237
|
+
body: error.body,
|
|
238
|
+
cause: error.cause,
|
|
239
|
+
});
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* @internal The one place a call runs: under one deadline, once, with a refused recording
|
|
244
|
+
* named and the no-replay rule applied to whatever it throws. Both wires go through here.
|
|
245
|
+
*/
|
|
246
|
+
export function transcribeOnce<T>(
|
|
247
|
+
provider: string,
|
|
248
|
+
timeoutMs: number,
|
|
249
|
+
request: TranscriptionRequest,
|
|
250
|
+
call: (signal: AbortSignal) => Promise<T>,
|
|
251
|
+
): Promise<T> {
|
|
252
|
+
return callOnce(
|
|
253
|
+
provider,
|
|
254
|
+
timeoutMs,
|
|
255
|
+
request.signal,
|
|
256
|
+
(signal) =>
|
|
257
|
+
call(signal).catch((error: unknown) => {
|
|
258
|
+
throw nameAudioRefusal(error);
|
|
259
|
+
}),
|
|
260
|
+
asTranscriptionError,
|
|
261
|
+
);
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
// ── replies ───────────────────────────────────────────────────────────────
|
|
265
|
+
|
|
266
|
+
/** @internal A reply that arrived but cannot be used. Never retried: it was billed. */
|
|
267
|
+
export function unusable(
|
|
268
|
+
provider: string,
|
|
269
|
+
message: string,
|
|
270
|
+
usage?: TranscriptionUsage,
|
|
271
|
+
): TranscriptionError {
|
|
272
|
+
return new TranscriptionError(provider, "unknown", `${provider}: ${message}`, {
|
|
273
|
+
code: "bad_reply",
|
|
274
|
+
shouldRetry: false,
|
|
275
|
+
...(usage ? { usage } : {}),
|
|
276
|
+
});
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* @internal A failure the provider reported inside a 200 (a gateway that answers 200 with a
|
|
281
|
+
* JSON error). Classified like any other failure, with the same words-over-status rules, and
|
|
282
|
+
* the provider's words kept: unlike speech, nothing the caller sent can come back in them.
|
|
283
|
+
*/
|
|
284
|
+
export function inBandFailure(provider: string, envelope: unknown): TranscriptionError {
|
|
285
|
+
const found = streamError(provider, envelope);
|
|
286
|
+
return new TranscriptionError(provider, found.kind, found.message, {
|
|
287
|
+
status: found.status,
|
|
288
|
+
code: found.code,
|
|
289
|
+
retryAfterMs: found.retryAfterMs,
|
|
290
|
+
resetAtMs: found.resetAtMs,
|
|
291
|
+
window: found.window,
|
|
292
|
+
body: found.body,
|
|
293
|
+
});
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/** @internal */
|
|
297
|
+
export function asRecord(value: unknown): Record<string, unknown> | undefined {
|
|
298
|
+
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
299
|
+
? (value as Record<string, unknown>)
|
|
300
|
+
: undefined;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/** @internal The reply as a JSON object, or `undefined` for anything else. */
|
|
304
|
+
export function parseObject(bytes: Uint8Array): Record<string, unknown> | undefined {
|
|
305
|
+
try {
|
|
306
|
+
return asRecord(JSON.parse(new TextDecoder().decode(bytes)));
|
|
307
|
+
} catch {
|
|
308
|
+
return undefined;
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/** @internal A finite, non-negative number of seconds, or `undefined`. */
|
|
313
|
+
export const seconds = (value: unknown): number | undefined =>
|
|
314
|
+
typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* @internal The segments that check out: a start and an end in seconds, end not before start,
|
|
318
|
+
* and text. A malformed one is skipped rather than guessed at. `speaker` is read only when the
|
|
319
|
+
* caller asked for speakers, so a provider that stamps speaker 0 on everyone without being asked
|
|
320
|
+
* does not label a monologue.
|
|
321
|
+
*/
|
|
322
|
+
export function readSegments(
|
|
323
|
+
raw: unknown,
|
|
324
|
+
textKey: string,
|
|
325
|
+
diarize: boolean,
|
|
326
|
+
): TranscriptionSegment[] {
|
|
327
|
+
if (!Array.isArray(raw)) return [];
|
|
328
|
+
const segments: TranscriptionSegment[] = [];
|
|
329
|
+
for (const entry of raw) {
|
|
330
|
+
const segment = asRecord(entry);
|
|
331
|
+
const start = seconds(segment?.start);
|
|
332
|
+
const end = seconds(segment?.end);
|
|
333
|
+
const text = segment?.[textKey];
|
|
334
|
+
if (start === undefined || end === undefined || end < start || typeof text !== "string") {
|
|
335
|
+
continue;
|
|
336
|
+
}
|
|
337
|
+
const speaker = segment?.speaker;
|
|
338
|
+
const labelled =
|
|
339
|
+
diarize &&
|
|
340
|
+
((typeof speaker === "number" && Number.isSafeInteger(speaker) && speaker >= 0) ||
|
|
341
|
+
(typeof speaker === "string" && speaker !== ""));
|
|
342
|
+
segments.push({ start, end, text: text.trim(), ...(labelled ? { speaker } : {}) });
|
|
343
|
+
}
|
|
344
|
+
return segments;
|
|
345
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// `@providerkit/core/transcription`: one recording to its text, the inverse of
|
|
2
|
+
// `@providerkit/core/speech`. It is its own entry point, and `index.ts` does not export it, so
|
|
3
|
+
// an app that only chats loads none of the transcription code.
|
|
4
|
+
//
|
|
5
|
+
// Named, not `export *`: transcription-core.ts also holds helpers the two wires share, and a
|
|
6
|
+
// helper exported here is one this package can never change without a major version.
|
|
7
|
+
export {
|
|
8
|
+
DEFAULT_TRANSCRIPTION_LIMITS,
|
|
9
|
+
TranscriptionError,
|
|
10
|
+
type TranscriptionLimits,
|
|
11
|
+
type TranscriptionProvider,
|
|
12
|
+
type TranscriptionRequest,
|
|
13
|
+
type TranscriptionResult,
|
|
14
|
+
type TranscriptionSegment,
|
|
15
|
+
type TranscriptionShape,
|
|
16
|
+
type TranscriptionUsage,
|
|
17
|
+
} from "./transcription-core.ts";
|
|
18
|
+
// The `fetchImpl` option's type, so a transcription-only app can type its wrapper without the
|
|
19
|
+
// main entry.
|
|
20
|
+
export type { FetchLike } from "./transport.ts";
|
|
21
|
+
export * from "./providers/openai-transcription.ts";
|
|
22
|
+
export * from "./providers/deepgram-transcription.ts";
|
|
23
|
+
export * from "./providers/transcription-factory.ts";
|
|
24
|
+
export { TRANSCRIPTION_PRESET_IDS, type PresetTranscription } from "./presets.ts";
|
package/src/transport.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
//
|
|
5
5
|
// Adapters keep only their per-event mapping; everything about being an HTTP
|
|
6
6
|
// client lives here once.
|
|
7
|
-
import { classifyHttp, parseRetryAfterMs, ProviderError } from "./errors.ts";
|
|
7
|
+
import { classifyHttp, parseRetryAfterMs, ProviderError, type ErrorKind } from "./errors.ts";
|
|
8
8
|
import {
|
|
9
9
|
parseRateLimitReset,
|
|
10
10
|
parseRateLimitResponse,
|
|
@@ -198,13 +198,17 @@ function originOf(url: string): string {
|
|
|
198
198
|
*/
|
|
199
199
|
async function send(opts: RequestInit_, method = "POST", redact = false): Promise<Response> {
|
|
200
200
|
const doFetch = opts.fetchImpl ?? globalThis.fetch;
|
|
201
|
+
// A Blob (a recording) or a FormData (a multipart upload) goes as itself, and fetch writes its
|
|
202
|
+
// Content-Type: a multipart boundary is one only fetch knows, so a JSON type here would break it.
|
|
203
|
+
const payload = opts.body;
|
|
204
|
+
const raw = payload instanceof Blob || payload instanceof FormData;
|
|
201
205
|
// Serialized outside the catch below: a body that cannot become JSON is a
|
|
202
206
|
// bug of ours, and must not be dressed as a network blip and retried.
|
|
203
|
-
const body = typeof
|
|
207
|
+
const body = raw || typeof payload === "string" ? payload : JSON.stringify(payload);
|
|
204
208
|
try {
|
|
205
209
|
return await doFetch(opts.url, {
|
|
206
210
|
method,
|
|
207
|
-
headers: { "content-type": "application/json", ...opts.headers },
|
|
211
|
+
headers: raw ? { ...opts.headers } : { "content-type": "application/json", ...opts.headers },
|
|
208
212
|
body,
|
|
209
213
|
signal: opts.signal,
|
|
210
214
|
...(opts.redirect ? { redirect: opts.redirect } : {}),
|
|
@@ -361,6 +365,76 @@ export async function withDeadline<T>(
|
|
|
361
365
|
}
|
|
362
366
|
}
|
|
363
367
|
|
|
368
|
+
type ProviderErrorOptions = NonNullable<ConstructorParameters<typeof ProviderError>[3]>;
|
|
369
|
+
|
|
370
|
+
/** How a capability copies one of its own errors, so a subclass comes back as itself
|
|
371
|
+
* with what it carries (the usage a speech or transcription error keeps). */
|
|
372
|
+
export type ErrorRebuild = (err: ProviderError, opts: ProviderErrorOptions) => ProviderError;
|
|
373
|
+
|
|
374
|
+
const plainCopy: ErrorRebuild = (err, opts) =>
|
|
375
|
+
new ProviderError(err.provider, err.kind, err.message, opts);
|
|
376
|
+
|
|
377
|
+
/** Kinds that can land after the vendor started the work it bills for. */
|
|
378
|
+
const REPLAY_UNSAFE: ReadonlySet<ErrorKind> = new Set<ErrorKind>([
|
|
379
|
+
"network",
|
|
380
|
+
"timeout",
|
|
381
|
+
"overload",
|
|
382
|
+
"unknown",
|
|
383
|
+
]);
|
|
384
|
+
|
|
385
|
+
/**
|
|
386
|
+
* @internal The "could the vendor already have billed this?" rule (invariant 16), for every
|
|
387
|
+
* call that is paid for whole and answered whole: speech and transcription. Kept here, once,
|
|
388
|
+
* so a new capability or a new failure path cannot forget it.
|
|
389
|
+
*
|
|
390
|
+
* - The caller's Stop comes back untouched.
|
|
391
|
+
* - A timeout, a dead socket, a 5xx or anything unclassified may have landed after
|
|
392
|
+
* the vendor started work, so it is marked `shouldRetry: false`, and a vendor's
|
|
393
|
+
* `x-should-retry: true` does not undo that: the header says the vendor thinks a
|
|
394
|
+
* resend is fine, not that the first call was not billed.
|
|
395
|
+
* - Every other kind keeps what it came with. A 429 means the vendor refused before
|
|
396
|
+
* doing any work, so sending it again is safe, and `Retry-After` is honoured by
|
|
397
|
+
* the caller's own retry. `x-should-retry` is believed there, in either direction.
|
|
398
|
+
*/
|
|
399
|
+
export function noReplay(
|
|
400
|
+
provider: string,
|
|
401
|
+
error: unknown,
|
|
402
|
+
signal?: AbortSignal,
|
|
403
|
+
rebuild: ErrorRebuild = plainCopy,
|
|
404
|
+
): unknown {
|
|
405
|
+
if (signal?.aborted) return error;
|
|
406
|
+
const err = ProviderError.from(provider, error);
|
|
407
|
+
if (!REPLAY_UNSAFE.has(err.kind) || err.shouldRetry === false) return err;
|
|
408
|
+
return rebuild(err, {
|
|
409
|
+
status: err.status,
|
|
410
|
+
code: err.code,
|
|
411
|
+
retryAfterMs: err.retryAfterMs,
|
|
412
|
+
resetAtMs: err.resetAtMs,
|
|
413
|
+
window: err.window,
|
|
414
|
+
shouldRetry: false,
|
|
415
|
+
body: err.body,
|
|
416
|
+
cause: err.cause,
|
|
417
|
+
});
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/**
|
|
421
|
+
* @internal The one place a paid call runs: under one deadline, once, with `noReplay`
|
|
422
|
+
* applied to whatever it throws.
|
|
423
|
+
*/
|
|
424
|
+
export async function callOnce<T>(
|
|
425
|
+
provider: string,
|
|
426
|
+
timeoutMs: number,
|
|
427
|
+
signal: AbortSignal | undefined,
|
|
428
|
+
call: (signal: AbortSignal) => Promise<T>,
|
|
429
|
+
rebuild?: ErrorRebuild,
|
|
430
|
+
): Promise<T> {
|
|
431
|
+
try {
|
|
432
|
+
return await withDeadline(provider, timeoutMs, signal, call);
|
|
433
|
+
} catch (error) {
|
|
434
|
+
throw noReplay(provider, error, signal, rebuild);
|
|
435
|
+
}
|
|
436
|
+
}
|
|
437
|
+
|
|
364
438
|
/** Pull the `data:` payload out of one SSE frame, joining continuation lines
|
|
365
439
|
* the way the spec says to. Returns null for a comment or a frame carrying
|
|
366
440
|
* only an `event:` name. */
|