@opencode/ai 0.0.0-dev-20048 → 0.0.0-dev-20052

package/README.md

@@ -766,6 +766,69 @@ for await (const event of ai.speech.stream({ model, text: "Hello from OpenCode."
 }
 ```
 
+## Transcription
+
+Transcription (speech-to-text) is the one modality whose providers use every route kind: OpenAI and Gemini stream,
+Deepgram answers inline, and AssemblyAI is queued. `Transcription.generate` and `Transcription.stream` work on all of
+them; `Transcription.start` / `resume` return a `Generation` on queued routes and fail with `UnsupportedOperation`
+elsewhere. Models come from `.transcription(...)` selectors on the `OpenAI`, `Google`, `Deepgram`, and `AssemblyAI`
+facades. Common fields (`language`, `prompt`, `timestamps: "none" | "segment" | "word"`, `diarize`, `speakers`) lower
+natively or fail with a typed `AIError` before any network call; a route may return more than asked.
+
+```ts
+import { Media, Transcription, TranscriptionEvent } from "@opencode/ai"
+import { AssemblyAI, Deepgram, OpenAI } from "@opencode/ai/providers"
+
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
+
+const program = Effect.gen(function* () {
+  const audio = yield* Media.file("./call.mp3")
+
+  // Speaker-labelled segments; labels are provider-native strings ("A", "0", "spk:0").
+  const response = yield* Transcription.generate({
+    model: Deepgram.configure({ apiKey }).transcription("nova-3"),
+    audio,
+    diarize: true,
+    timestamps: "word",
+  })
+  response.text // "Hello from OpenCode."
+  response.segments // [{ text, startSeconds, endSeconds, speaker: "0" }]
+  response.words // [{ text, startSeconds, endSeconds, speaker, confidence }]
+  response.language // the provider's own value, lowercased ("en", "english", "en_us")
+
+  // Text deltas as the model transcribes, then one finish carrying the whole transcript.
+  yield* Transcription.stream({ model: openai.transcription("gpt-4o-mini-transcribe"), audio }).pipe(
+    Stream.tap((event) => (TranscriptionEvent.is.textDelta(event) ? Console.log(event.delta) : Effect.void)),
+    Stream.runDrain,
+  )
+
+  // Queued: persist the token, resume from another process, and await.
+  const model = AssemblyAI.configure({ apiKey }).transcription("universal-3-5-pro")
+  const generation = yield* Transcription.start({ model, audio })
+  const resumed = yield* Transcription.resume(model, JSON.parse(JSON.stringify(generation.token)))
+  const transcript = yield* resumed.await({ poll: { interval: "3 seconds" } })
+})
+```
+
+Inline routes emit only `finish` from `stream` (no faked deltas); queued routes emit `generation-queued` /
+`generation-progress` before it. `TranscriptionClient.layer` needs `RequestExecutor.Service`.
+
+Provider notes:
+
+- **OpenAI** takes inline audio only; `diarize` needs `gpt-4o-transcribe-diarize`, timestamps need `whisper-1`, and `whisper-1` does not stream.
+- **Gemini** needs a transcribe model (`gemini-3.5-transcribe`); `prompt` and `speakers` fail typed.
+- **Deepgram** detects the language unless `language` is set; vocabulary goes in `providerOptions.keyterm`.
+- **AssemblyAI** uploads inline audio before submitting and is the only route that accepts `speakers`.
+
+The promise client mirrors the Effect API:
+
+```ts
+const text = (await ai.transcription.generate({ model, audio })).text
+for await (const event of ai.transcription.stream({ model, audio })) if (event.type === "text-delta") write(event.delta)
+const generation = await ai.transcription.start({ model: assemblyai, audio })
+const transcript = await generation.await({ poll: { interval: 3_000 } })
+```
+
 ## Public API
 
 - **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
@@ -778,7 +841,8 @@ for await (const event of ai.speech.stream({ model, text: "Hello from OpenCode."
 - **`Media`** — the shared asset type (`Media.Asset`, `Media.Source`) and constructors used by messages, tool results, and media requests.
 - **`Generation`** — provider-neutral handle for an in-flight media generation (`await`, `refresh`, `cancel`, `events`) used by queued media routes.
 - **`Speech.request` / `Speech.generate` / `Speech.stream`** — text-to-speech through a provider-neutral request; `SpeechClient` is its Effect service and layer.
-- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, and `speech` as Promise / `AsyncIterable` APIs.
+- **`Transcription.request` / `generate` / `stream` / `start` / `resume`** — speech-to-text over inline, streaming, and queued routes; `TranscriptionClient` is its Effect service and layer.
+- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, and `transcription` as Promise / `AsyncIterable` APIs.
 
 ## Testing
 

package/dist/generation.d.ts

@@ -33,15 +33,18 @@ export interface AwaitOptions {
 }
 export declare const DEFAULT_POLL_INTERVAL: Duration.Duration;
 export declare const DEFAULT_POLL_TIMEOUT: Duration.Duration;
-export type Event = {
-    readonly type: "generation-queued";
-    readonly id: string;
-    readonly position?: number;
-} | {
-    readonly type: "generation-progress";
-    readonly id: string;
-    readonly progress?: number;
-} | {
+export declare const QueuedEvent: Schema.Struct<{
+    readonly type: Schema.tag<"generation-queued">;
+    readonly id: Schema.String;
+    readonly position: Schema.optional<Schema.Number>;
+}>;
+export declare const ProgressEvent: Schema.Struct<{
+    readonly type: Schema.tag<"generation-progress">;
+    readonly id: Schema.String;
+    readonly progress: Schema.optional<Schema.Number>;
+}>;
+export type Observation = Schema.Schema.Type<typeof QueuedEvent> | Schema.Schema.Type<typeof ProgressEvent>;
+export type Event = Observation | {
     readonly type: "generation-finished";
     readonly id: string;
     readonly status: Status;
@@ -77,3 +80,4 @@ export declare class Generation<Response> {
     private poll;
     private schedule;
 }
+export declare const resultEvents: <Response, A>(generation: Generation<Response>, expand: (response: Response) => ReadonlyArray<A>, options?: AwaitOptions) => Stream.Stream<Observation | A, AIError>;

package/dist/generation.js

@@ -3,6 +3,16 @@ import { AIError, TimeoutError } from "./schema/errors.js";
 export const Status = Schema.Literals(["queued", "running", "completed", "failed", "cancelled", "expired"]);
 export const DEFAULT_POLL_INTERVAL = Duration.seconds(5);
 export const DEFAULT_POLL_TIMEOUT = Duration.minutes(10);
+export const QueuedEvent = Schema.Struct({
+    type: Schema.tag("generation-queued"),
+    id: Schema.String,
+    position: Schema.optional(Schema.Number),
+}).annotate({ identifier: "Generation.Event.Queued" });
+export const ProgressEvent = Schema.Struct({
+    type: Schema.tag("generation-progress"),
+    id: Schema.String,
+    progress: Schema.optional(Schema.Number),
+}).annotate({ identifier: "Generation.Event.Progress" });
 const TERMINAL = new Set(["completed", "failed", "cancelled", "expired"]);
 export class Generation {
     route;
@@ -100,3 +110,4 @@ export class Generation {
         return spaced.pipe(Schedule.modifyDelay((metadata) => Effect.succeed(pollHint(metadata.input.snapshot) ?? interval)));
     }
 }
+export const resultEvents = (generation, expand, options) => generation.events(options).pipe(Stream.filter((event) => event.type !== "generation-finished"), Stream.concat(Stream.fromIterableEffect(Effect.map(generation.result(), expand))));

package/dist/index.d.ts

@@ -17,6 +17,10 @@ export { SpeechClient } from "./speech-client.js";
 export { SpeechEvent, SpeechModel, SpeechModelSchema, SpeechRequest, SpeechResponse, SpeechTimestamp, SpeechVoice, } from "./speech.js";
 export type { SpeechFormat, SpeechModelOptions, SpeechOptions, SpeechRequestFor, SpeechRequestInput, SpeechRoute, } from "./speech.js";
 export { Speech } from "./speech.js";
+export { TranscriptionClient } from "./transcription-client.js";
+export { TranscriptionEvent, TranscriptionModel, TranscriptionModelSchema, TranscriptionRequest, TranscriptionResponse, TranscriptionSegment, TranscriptionTimestamps, TranscriptionWord, } from "./transcription.js";
+export type { TranscriptionModelOptions, TranscriptionOptions, TranscriptionRequestFor, TranscriptionRequestInput, TranscriptionRoute, } from "./transcription.js";
+export { Transcription } from "./transcription.js";
 export { Media } from "./media.js";
 export { Generation } from "./generation.js";
 export type { AwaitOptions as GenerationAwaitOptions, Event as GenerationEvent, Poll, Route as GenerationRoute, Snapshot as GenerationSnapshot, Status as GenerationStatus, } from "./generation.js";

package/dist/index.js

@@ -13,6 +13,9 @@ export { Video } from "./video.js";
 export { SpeechClient } from "./speech-client.js";
 export { SpeechEvent, SpeechModel, SpeechModelSchema, SpeechRequest, SpeechResponse, SpeechTimestamp, SpeechVoice, } from "./speech.js";
 export { Speech } from "./speech.js";
+export { TranscriptionClient } from "./transcription-client.js";
+export { TranscriptionEvent, TranscriptionModel, TranscriptionModelSchema, TranscriptionRequest, TranscriptionResponse, TranscriptionSegment, TranscriptionTimestamps, TranscriptionWord, } from "./transcription.js";
+export { Transcription } from "./transcription.js";
 export { Media } from "./media.js";
 export { Generation } from "./generation.js";
 export { Tool, ToolFailure, toDefinitions } from "./tool.js";

package/dist/promise.d.ts

@@ -8,11 +8,14 @@ import { LanguageModel, LLMRequest } from "./schema/index.js";
 import type { RequestInput } from "./llm.js";
 import { SpeechModel, SpeechRequest, type SpeechRequestInput } from "./speech.js";
 import { SpeechClient } from "./speech-client.js";
+import { TranscriptionModel, TranscriptionRequest, type TranscriptionOptions, type TranscriptionRequestInput } from "./transcription.js";
+import { TranscriptionClient } from "./transcription-client.js";
 import { VideoModel, VideoRequest, type VideoOptions, type VideoRequestInput } from "./video.js";
 import { VideoClient } from "./video-client.js";
 /**
- * Promise-first entrypoint for scripts and non-Effect callers. One `ManagedRuntime` hosts the LLM, image, video, and
- * speech clients over a request executor; every method runs the corresponding Effect API and rethrows `AIError` unchanged.
+ * Promise-first entrypoint for scripts and non-Effect callers. One `ManagedRuntime` hosts the LLM, image, video, speech,
+ * and transcription clients over a request executor; every method runs the corresponding Effect API and rethrows
+ * `AIError` unchanged.
  */
 export interface Options {
     /** Executor layer; defaults to `RequestExecutor.fetchLayer`. Inject a recorder or middleware here. */
@@ -21,7 +24,7 @@ export interface Options {
 export interface RunOptions {
     readonly signal?: AbortSignal;
 }
-export type Services = Layer.Success<typeof LLMClient.layer> | Layer.Success<typeof ImageClient.layer> | Layer.Success<typeof VideoClient.layer> | Layer.Success<typeof SpeechClient.layer> | RequestExecutor.Service;
+export type Services = Layer.Success<typeof LLMClient.layer> | Layer.Success<typeof ImageClient.layer> | Layer.Success<typeof VideoClient.layer> | Layer.Success<typeof SpeechClient.layer> | Layer.Success<typeof TranscriptionClient.layer> | RequestExecutor.Service;
 /** Promise view of a `Generation`: its snapshot plus `await`, `refresh`, and `cancel` returning promises. */
 export type GenerationHandle<Response> = Snapshot & {
     /** Serializable JSON; pass it back to `resume` from another process. */
@@ -403,6 +406,85 @@ export declare const make: (options?: Options) => {
             }[] | undefined;
         }>;
     };
+    transcription: {
+        request: typeof import("./transcription.js").request;
+        generate: <const Model extends TranscriptionModel>(input: TranscriptionRequestInput<Model> | TranscriptionRequest, options?: AwaitOptions & RunOptions) => Promise<import("./transcription.js").TranscriptionResponse>;
+        stream: <const Model extends TranscriptionModel>(input: TranscriptionRequestInput<Model> | TranscriptionRequest, options?: AwaitOptions & RunOptions) => AsyncIterable<{
+            readonly id: string;
+            readonly type: "generation-queued";
+            readonly position?: number | undefined;
+        } | {
+            readonly id: string;
+            readonly type: "generation-progress";
+            readonly progress?: number | undefined;
+        } | {
+            readonly type: "text-delta";
+            readonly delta: string;
+        } | {
+            readonly type: "segment";
+            readonly segment: {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+                readonly speaker?: string | undefined;
+            };
+        } | {
+            readonly type: "finish";
+            readonly text: string;
+            readonly durationSeconds?: number | undefined;
+            readonly providerMetadata?: {
+                readonly [x: string]: {
+                    readonly [x: string]: unknown;
+                };
+            } | undefined;
+            readonly usage?: {
+                readonly type: "tokens";
+                readonly input?: number | undefined;
+                readonly output?: number | undefined;
+                readonly total?: number | undefined;
+                readonly details?: {
+                    readonly [x: string]: unknown;
+                } | undefined;
+            } | {
+                readonly type: "seconds";
+                readonly seconds: number;
+            } | {
+                readonly type: "characters";
+                readonly characters: number;
+            } | {
+                readonly type: "credits";
+                readonly credits: number;
+            } | {
+                readonly type: "compute";
+                readonly seconds: number;
+            } | undefined;
+            readonly notices?: readonly {
+                readonly type: "other" | "moderated" | "filtered";
+                readonly message: string;
+                readonly providerMetadata?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                    };
+                } | undefined;
+            }[] | undefined;
+            readonly language?: string | undefined;
+            readonly segments?: readonly {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+                readonly speaker?: string | undefined;
+            }[] | undefined;
+            readonly words?: readonly {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+                readonly speaker?: string | undefined;
+                readonly confidence?: number | undefined;
+            }[] | undefined;
+        }>;
+        start: <const Model extends TranscriptionModel>(input: TranscriptionRequestInput<Model> | TranscriptionRequest, options?: RunOptions) => Promise<GenerationHandle<import("./transcription.js").TranscriptionResponse>>;
+        resume: <Options extends TranscriptionOptions>(model: TranscriptionModel<Options>, token: unknown, options?: RunOptions) => Promise<GenerationHandle<import("./transcription.js").TranscriptionResponse>>;
+    };
     dispose: () => Promise<void>;
 };
 export type Client = ReturnType<typeof make>;
@@ -780,6 +862,85 @@ export declare const ai: {
             }[] | undefined;
         }>;
     };
+    transcription: {
+        request: typeof import("./transcription.js").request;
+        generate: <const Model extends TranscriptionModel>(input: TranscriptionRequestInput<Model> | TranscriptionRequest, options?: AwaitOptions & RunOptions) => Promise<import("./transcription.js").TranscriptionResponse>;
+        stream: <const Model extends TranscriptionModel>(input: TranscriptionRequestInput<Model> | TranscriptionRequest, options?: AwaitOptions & RunOptions) => AsyncIterable<{
+            readonly id: string;
+            readonly type: "generation-queued";
+            readonly position?: number | undefined;
+        } | {
+            readonly id: string;
+            readonly type: "generation-progress";
+            readonly progress?: number | undefined;
+        } | {
+            readonly type: "text-delta";
+            readonly delta: string;
+        } | {
+            readonly type: "segment";
+            readonly segment: {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+                readonly speaker?: string | undefined;
+            };
+        } | {
+            readonly type: "finish";
+            readonly text: string;
+            readonly durationSeconds?: number | undefined;
+            readonly providerMetadata?: {
+                readonly [x: string]: {
+                    readonly [x: string]: unknown;
+                };
+            } | undefined;
+            readonly usage?: {
+                readonly type: "tokens";
+                readonly input?: number | undefined;
+                readonly output?: number | undefined;
+                readonly total?: number | undefined;
+                readonly details?: {
+                    readonly [x: string]: unknown;
+                } | undefined;
+            } | {
+                readonly type: "seconds";
+                readonly seconds: number;
+            } | {
+                readonly type: "characters";
+                readonly characters: number;
+            } | {
+                readonly type: "credits";
+                readonly credits: number;
+            } | {
+                readonly type: "compute";
+                readonly seconds: number;
+            } | undefined;
+            readonly notices?: readonly {
+                readonly type: "other" | "moderated" | "filtered";
+                readonly message: string;
+                readonly providerMetadata?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                    };
+                } | undefined;
+            }[] | undefined;
+            readonly language?: string | undefined;
+            readonly segments?: readonly {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+                readonly speaker?: string | undefined;
+            }[] | undefined;
+            readonly words?: readonly {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+                readonly speaker?: string | undefined;
+                readonly confidence?: number | undefined;
+            }[] | undefined;
+        }>;
+        start: <const Model extends TranscriptionModel>(input: TranscriptionRequestInput<Model> | TranscriptionRequest, options?: RunOptions) => Promise<GenerationHandle<import("./transcription.js").TranscriptionResponse>>;
+        resume: <Options extends TranscriptionOptions>(model: TranscriptionModel<Options>, token: unknown, options?: RunOptions) => Promise<GenerationHandle<import("./transcription.js").TranscriptionResponse>>;
+    };
     dispose: () => Promise<void>;
 };
 export * as AI from "./promise.js";

package/dist/promise.js

@@ -7,6 +7,8 @@ import { RequestExecutor } from "./route/executor.js";
 import { LanguageModel, LLMRequest } from "./schema/index.js";
 import { Speech, SpeechModel, SpeechRequest } from "./speech.js";
 import { SpeechClient } from "./speech-client.js";
+import { Transcription, TranscriptionModel, TranscriptionRequest, } from "./transcription.js";
+import { TranscriptionClient } from "./transcription-client.js";
 import { Video, VideoModel, VideoRequest } from "./video.js";
 import { VideoClient } from "./video-client.js";
 const abortEffect = (signal) => signal === undefined
@@ -21,7 +23,7 @@ const abortEffect = (signal) => signal === undefined
         return Effect.sync(() => signal.removeEventListener("abort", onAbort));
     });
 export const make = (options = {}) => {
-    const runtime = ManagedRuntime.make(Layer.mergeAll(LLMClient.layer, ImageClient.layer, VideoClient.layer, SpeechClient.layer).pipe(Layer.provideMerge(options.layer ?? RequestExecutor.fetchLayer)));
+    const runtime = ManagedRuntime.make(Layer.mergeAll(LLMClient.layer, ImageClient.layer, VideoClient.layer, SpeechClient.layer, TranscriptionClient.layer).pipe(Layer.provideMerge(options.layer ?? RequestExecutor.fetchLayer)));
     /** Run any package Effect (for example `asset.bytes()`) inside this runtime. */
     const run = (effect, options) => runtime.runPromise(effect, { signal: options?.signal });
     const iterate = (stream, options) => Stream.toAsyncIterable(Stream.unwrap(runtime.contextEffect.pipe(Effect.map((context) => stream.pipe(Stream.interruptWhen(abortEffect(options?.signal)), Stream.provideContext(context))))));
@@ -37,6 +39,7 @@ export const make = (options = {}) => {
     const imageRequest = (input) => input instanceof ImageRequest ? input : Image.request(input);
     const videoRequest = (input) => input instanceof VideoRequest ? input : Video.request(input);
     const speechRequest = (input) => input instanceof SpeechRequest ? input : Speech.request(input);
+    const transcriptionRequest = (input) => input instanceof TranscriptionRequest ? input : Transcription.request(input);
     return {
         run,
         llm: {
@@ -61,6 +64,13 @@ export const make = (options = {}) => {
             generate: (input, options) => run(Speech.generate(speechRequest(input)), options),
             stream: (input, options) => iterate(Speech.stream(speechRequest(input)), options),
         },
+        transcription: {
+            request: Transcription.request,
+            generate: (input, options) => run(Transcription.generate(transcriptionRequest(input), { poll: options?.poll }), options),
+            stream: (input, options) => iterate(Transcription.stream(transcriptionRequest(input), { poll: options?.poll }), options),
+            start: (input, options) => run(Transcription.start(transcriptionRequest(input)), options).then(handle),
+            resume: (model, token, options) => run(Transcription.resume(model, token), options).then(handle),
+        },
         dispose: () => runtime.dispose(),
     };
 };

package/dist/protocols/assemblyai-transcription.d.ts

@@ -0,0 +1,40 @@
+import { Schema } from "effect";
+import { MediaProtocol } from "../route/media-protocol.js";
+import { MediaRoute } from "../route/media.js";
+import { TranscriptionModel, TranscriptionResponse, type TranscriptionRequestFor } from "../transcription.js";
+export declare const DEFAULT_BASE_URL = "https://api.assemblyai.com";
+export declare const PATH = "/v2/transcript";
+export declare const UPLOAD_PATH = "/v2/upload";
+export type AssemblyAITranscriptionOptions = {
+    readonly keyterms_prompt?: ReadonlyArray<string>;
+    readonly punctuate?: boolean;
+    readonly format_text?: boolean;
+    readonly disfluencies?: boolean;
+    readonly filter_profanity?: boolean;
+    readonly temperature?: number;
+    readonly speaker_options?: {
+        readonly min_speakers_expected?: number;
+        readonly max_speakers_expected?: number;
+    };
+    readonly language_detection_options?: {
+        readonly expected_languages?: ReadonlyArray<string>;
+        readonly fallback_language?: string;
+        readonly code_switching?: boolean;
+    };
+    readonly speech_models?: ReadonlyArray<"universal-3-5-pro" | "universal-2" | (string & {})>;
+} & Record<string, unknown>;
+export type Request = TranscriptionRequestFor<AssemblyAITranscriptionOptions>;
+export declare const Token: Schema.Struct<{
+    readonly transcriptID: Schema.String;
+}>;
+export type Token = Schema.Schema.Type<typeof Token>;
+export declare const protocol: MediaProtocol.Queued<Request, TranscriptionResponse, {
+    readonly transcriptID: string;
+}>;
+export declare const model: (input: MediaRoute.ModelInput) => TranscriptionModel<AssemblyAITranscriptionOptions>;
+export declare const AssemblyAITranscription: {
+    readonly protocol: MediaProtocol.Queued<Request, TranscriptionResponse, {
+        readonly transcriptID: string;
+    }>;
+    readonly model: (input: MediaRoute.ModelInput) => TranscriptionModel<AssemblyAITranscriptionOptions>;
+};

package/dist/protocols/assemblyai-transcription.js

@@ -0,0 +1,138 @@
+import { Effect, Schema } from "effect";
+import { Media } from "../media.js";
+import { MediaProtocol } from "../route/media-protocol.js";
+import { MediaRoute } from "../route/media.js";
+import { ProviderID, mergeJsonRecords } from "../schema/index.js";
+import { TranscriptionModel, TranscriptionResponse } from "../transcription.js";
+import { ProviderShared, optionalNull } from "./shared.js";
+import { MediaInput } from "./utils/media-input.js";
+const ADAPTER = "assemblyai-transcription";
+const NAME = "AssemblyAI";
+const PROVIDER = ProviderID.make("assemblyai");
+export const DEFAULT_BASE_URL = "https://api.assemblyai.com";
+export const PATH = "/v2/transcript";
+export const UPLOAD_PATH = "/v2/upload";
+// ---------------------------------------------------------------------------
+// 2. Token and response schemas
+// ---------------------------------------------------------------------------
+export const Token = Schema.Struct({ transcriptID: Schema.String });
+const Upload = Schema.Struct({ upload_url: Schema.String });
+/** Word and utterance times are milliseconds. */
+const Transcript = Schema.Struct({
+    id: Schema.String,
+    status: Schema.String,
+    text: optionalNull(Schema.String),
+    words: optionalNull(Schema.Array(Schema.Struct({
+        text: Schema.String,
+        start: Schema.Number,
+        end: Schema.Number,
+        confidence: optionalNull(Schema.Number),
+        speaker: optionalNull(Schema.String),
+    }))),
+    utterances: optionalNull(Schema.Array(Schema.Struct({
+        text: Schema.String,
+        start: Schema.Number,
+        end: Schema.Number,
+        speaker: optionalNull(Schema.String),
+    }))),
+    language_code: optionalNull(Schema.String),
+    audio_duration: optionalNull(Schema.Number),
+    speech_model_used: optionalNull(Schema.String),
+    error: optionalNull(Schema.String),
+});
+const STATUS = {
+    queued: "queued",
+    processing: "running",
+    completed: "completed",
+    error: "failed",
+};
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
+const decodeUpload = MediaProtocol.decodeJson(ADAPTER, NAME, Upload);
+/** `/v2/transcript` only takes a URL, so inline audio is uploaded to `/v2/upload` first. */
+const prepare = Effect.fn("AssemblyAITranscription.prepare")(function* (request, send) {
+    if (request.audio.source.type !== "bytes" && request.audio.source.type !== "base64")
+        return request;
+    const audio = yield* MediaInput.inlineBytes(ADAPTER, request.audio);
+    const uploaded = yield* send(UPLOAD_PATH, MediaProtocol.binary(audio, "application/octet-stream")).pipe(Effect.flatMap(decodeUpload));
+    return { ...request, audio: Media.url(uploaded.value.upload_url, { mediaType: request.audio.mediaType }) };
+});
+const fromRequest = Effect.fn("AssemblyAITranscription.fromRequest")(function* (request) {
+    const audio = yield* ProviderShared.mediaReference(request.audio, PROVIDER, NAME);
+    return MediaProtocol.json(mergeJsonRecords({
+        audio_url: audio.value,
+        speech_models: [request.model.id],
+        language_code: request.language,
+        language_detection: request.language === undefined ? true : undefined,
+        prompt: request.prompt,
+        // Turn-level `utterances`, the only segments AssemblyAI returns, require speaker labels.
+        speaker_labels: request.diarize === true || request.timestamps === "segment" ? true : undefined,
+        speakers_expected: request.speakers,
+    }, request.providerOptions, request.http?.body) ?? {});
+});
+// ---------------------------------------------------------------------------
+// 6. Response decoding
+// ---------------------------------------------------------------------------
+const decodeTranscript = MediaProtocol.decodeJson(ADAPTER, NAME, Transcript);
+const decodeStart = Effect.fn("AssemblyAITranscription.decodeStart")(function* (response) {
+    const output = yield* decodeTranscript(response);
+    const status = yield* MediaProtocol.status(STATUS, output.value.status, output);
+    return { token: { transcriptID: output.value.id }, snapshot: { id: output.value.id, status } };
+});
+const decodeStatus = Effect.fn("AssemblyAITranscription.decodeStatus")(function* (response, context) {
+    const output = yield* decodeTranscript(response);
+    const status = yield* MediaProtocol.status(STATUS, output.value.status, output);
+    return { id: context.token.transcriptID, status };
+});
+const seconds = (milliseconds) => milliseconds / 1000;
+const decodeResult = Effect.fn("AssemblyAITranscription.decodeResult")(function* (response, context) {
+    const output = yield* decodeTranscript(response);
+    const transcript = output.value;
+    const status = yield* MediaProtocol.status(STATUS, transcript.status, output);
+    const error = transcript.error ?? undefined;
+    if (status === "failed")
+        return yield* output.ended("failed", `${NAME} transcription failed${error === undefined ? "" : `: ${error}`}`);
+    if (status !== "completed")
+        return yield* output.invalid(`${NAME} transcript ${context.token.transcriptID} has not finished`);
+    const duration = transcript.audio_duration ?? undefined;
+    return new TranscriptionResponse({
+        text: transcript.text ?? "",
+        segments: transcript.utterances?.map((utterance) => ({
+            text: utterance.text,
+            startSeconds: seconds(utterance.start),
+            endSeconds: seconds(utterance.end),
+            speaker: utterance.speaker ?? undefined,
+        })),
+        words: transcript.words?.map((word) => ({
+            text: word.text,
+            startSeconds: seconds(word.start),
+            endSeconds: seconds(word.end),
+            speaker: word.speaker ?? undefined,
+            confidence: word.confidence ?? undefined,
+        })),
+        language: transcript.language_code?.toLowerCase(),
+        durationSeconds: duration,
+        usage: duration === undefined ? undefined : { type: "seconds", seconds: duration },
+        providerMetadata: {
+            assemblyai: { transcriptId: transcript.id, speechModel: transcript.speech_model_used ?? undefined },
+        },
+    });
+});
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+const transcriptPath = (token) => `${PATH}/${token.transcriptID}`;
+export const protocol = MediaProtocol.queued({
+    id: ADAPTER,
+    name: NAME,
+    token: Token,
+    start: { prepare, body: { from: fromRequest }, decode: decodeStart },
+    status: { path: transcriptPath, decode: decodeStatus },
+    result: { path: transcriptPath, decode: decodeResult },
+});
+export const model = (input) => TranscriptionModel.fromRoute({ id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH }, input);
+export const AssemblyAITranscription = {
+    protocol,
+    model,
+};

package/dist/protocols/deepgram-speech.js

@@ -3,6 +3,7 @@ import { MediaProtocol } from "../route/media-protocol.js";
 import { MediaRoute } from "../route/media.js";
 import { ProviderID, mergeJsonRecords } from "../schema/index.js";
 import { SpeechModel } from "../speech.js";
+import { MediaInput } from "./utils/media-input.js";
 import { SpeechStream } from "./utils/speech-stream.js";
 const ADAPTER = "deepgram-speech";
 const NAME = "Deepgram";
@@ -20,29 +21,30 @@ const FORMATS = {
     flac: { encoding: "flac" },
     aac: { encoding: "aac" },
 };
-const queryValue = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : undefined;
-const queryParameters = (request) => {
+const audioFormat = (request) => {
     const format = request.format === undefined ? undefined : FORMATS[request.format];
-    const { encoding, container, sampleRate, bitRate, ...native } = request.providerOptions ?? {};
-    return Object.fromEntries(Object.entries({
+    return {
+        encoding: request.providerOptions?.encoding ?? format?.encoding,
+        container: request.providerOptions?.container ?? format?.container,
+    };
+};
+const queryParameters = (request) => {
+    const { encoding: _encoding, container: _container, sampleRate, bitRate, ...native } = request.providerOptions ?? {};
+    return MediaInput.query(ADAPTER, {
         ...native,
         model: request.model.id,
-        encoding: encoding ?? format?.encoding,
-        container: container ?? format?.container,
+        ...audioFormat(request),
         sample_rate: sampleRate,
         bit_rate: bitRate,
         speed: request.speed,
-    }).flatMap(([key, value]) => {
-        const text = queryValue(value);
-        return text === undefined ? [] : [[key, text]];
-    }));
+    });
 };
 const fromRequest = Effect.fn("DeepgramSpeech.fromRequest")(function* (request) {
     if (request.format !== undefined &&
         FORMATS[request.format] === undefined &&
         request.providerOptions?.encoding === undefined)
         return yield* SpeechStream.unsupportedFormat(PROVIDER, ADAPTER, `${NAME} has no encoding for format "${request.format}"; pass providerOptions.encoding`);
-    return MediaProtocol.json(mergeJsonRecords({ text: request.text }, request.http?.body) ?? {}, queryParameters(request));
+    return MediaProtocol.json(mergeJsonRecords({ text: request.text }, request.http?.body) ?? {}, yield* queryParameters(request));
 });
 // ---------------------------------------------------------------------------
 // 6. Stream parsing
@@ -55,15 +57,15 @@ const HEADERLESS_ENCODINGS = {
 const finish = (state, context) => {
     const headers = context.http.headers;
     const mediaType = headers["content-type"];
-    const query = queryParameters(context.request);
-    const encoding = HEADERLESS_ENCODINGS[query.encoding ?? ""];
+    const format = audioFormat(context.request);
+    const encoding = HEADERLESS_ENCODINGS[format.encoding ?? ""];
     const requestID = headers["dg-request-id"];
     const modelName = headers["dg-model-name"];
     return SpeechStream.finish(ADAPTER, state, {
-        ...(query.container === "none" && encoding !== undefined
+        ...(format.container === "none" && encoding !== undefined
             ? SpeechStream.pcm(encoding, SpeechStream.sampleRate(mediaType), mediaType)
             : // Deepgram's default encoding is MP3; WAV is a container around any encoding.
-                { mediaType, info: { format: query.container === "wav" ? "wav" : (query.encoding ?? "mp3") } }),
+                { mediaType, info: { format: format.container === "wav" ? "wav" : (format.encoding ?? "mp3") } }),
         usage: SpeechStream.headerUsage("characters", headers["dg-char-count"]),
         providerMetadata: requestID === undefined && modelName === undefined
             ? undefined