@effect-uai/google 0.3.0 → 0.5.0

package/src/codec.ts

@@ -1,5 +1,6 @@
 import { Array as Arr, Encoding, Match, Option, Result, Schema, pipe } from "effect"
-import type { ContentBlock, InputImage, Item, Message } from "@effect-uai/core/Items"
+import type { ContentBlock, FunctionCall, InputImage, Item, Message } from "@effect-uai/core/Items"
+import type { ToolDescriptor } from "@effect-uai/core/Tool"
 import type { Turn } from "@effect-uai/core/Turn"
 
 // ---------------------------------------------------------------------------
@@ -17,7 +18,22 @@ const TextPart = Schema.Struct({
   thought: Schema.optional(Schema.Boolean),
 })
 
-const Part = Schema.Union([TextPart])
+/**
+ * Gemini function-call part. Args are delivered as a whole JSON *object*
+ * in a single chunk (Gemini does not stream tool-call args). On Gemini 3
+ * the response also carries an `id` per call, which we echo back on the
+ * corresponding `functionResponse`.
+ */
+const FunctionCallPart = Schema.Struct({
+  functionCall: Schema.Struct({
+    id: Schema.optional(Schema.String),
+    name: Schema.String,
+    args: Schema.optional(Schema.Unknown),
+  }),
+})
+
+const Part = Schema.Union([TextPart, FunctionCallPart])
+type WireFunctionCallPart = typeof FunctionCallPart.Type
 
 const Content = Schema.Struct({
   role: Schema.optional(Schema.String),
@@ -51,6 +67,13 @@ export type WireChunk = typeof WireChunk.Type
 type RequestPart =
   | { readonly text: string }
   | { readonly inlineData: { readonly mimeType: string; readonly data: string } }
+  | { readonly functionCall: { readonly name: string; readonly args: unknown } }
+  | {
+      readonly functionResponse: {
+        readonly name: string
+        readonly response: Record<string, unknown>
+      }
+    }
 
 type RequestContent = {
   readonly role: "user" | "model"
@@ -61,6 +84,22 @@ type RequestSystemInstruction = {
   readonly parts: ReadonlyArray<{ readonly text: string }>
 }
 
+/** Gemini's tool declaration. We translate one `ToolDescriptor` per entry. */
+type RequestTool = {
+  readonly functionDeclarations: ReadonlyArray<{
+    readonly name: string
+    readonly description: string
+    readonly parameters: Record<string, unknown>
+  }>
+}
+
+type RequestToolConfig = {
+  readonly functionCallingConfig: {
+    readonly mode: "AUTO" | "ANY" | "NONE"
+    readonly allowedFunctionNames?: ReadonlyArray<string>
+  }
+}
+
 export type ThinkingConfig = {
   readonly thinkingBudget: number
 }
@@ -80,6 +119,8 @@ export type RequestBody = {
   readonly contents: ReadonlyArray<RequestContent>
   readonly systemInstruction?: RequestSystemInstruction
   readonly generationConfig?: GenerationConfig
+  readonly tools?: ReadonlyArray<RequestTool>
+  readonly toolConfig?: RequestToolConfig
 }
 
 const blockText = Match.type<ContentBlock>().pipe(
@@ -142,19 +183,165 @@ const systemMessageText = (message: Message): Result.Result<string, void> => {
   return text.length === 0 ? Result.failVoid : Result.succeed(text)
 }
 
-const messages = (history: ReadonlyArray<Item>): ReadonlyArray<Message> =>
+const allMessages = (history: ReadonlyArray<Item>): ReadonlyArray<Message> =>
   pipe(
     history,
     Arr.filterMap((item) => (item.type === "message" ? Result.succeed(item) : Result.failVoid)),
   )
 
+// ---------------------------------------------------------------------------
+// Function-call round-trip
+//
+// `FunctionCall.arguments` and `FunctionCallOutput.output` are JSON-encoded
+// strings; Gemini's `functionCall.args` and `functionResponse.response`
+// expect parsed JSON *objects*. Decode via Schema:
+//   - object payload → use as-is
+//   - scalar / array / malformed → wrap as `{ output: <raw string> }` so the
+//     model still sees *some* response without crashing the request.
+// ---------------------------------------------------------------------------
+
+const JsonObject = Schema.Record(Schema.String, Schema.Unknown)
+const decodeJsonObject = Schema.decodeResult(Schema.fromJsonString(JsonObject))
+
+const parsedJsonObject =
+  (fallback: (raw: string) => Record<string, unknown>) =>
+  (encoded: string): Record<string, unknown> =>
+    pipe(
+      decodeJsonObject(encoded),
+      Result.match({
+        onSuccess: (v) => v,
+        onFailure: () => fallback(encoded),
+      }),
+    )
+
+const parsedArgs = parsedJsonObject(() => ({}))
+const parsedResponse = parsedJsonObject((raw) => ({ output: raw }))
+
+/**
+ * `FunctionCallOutput` only carries `call_id`; Gemini's `functionResponse`
+ * requires the declared function `name`. Resolve the name by scanning prior
+ * `function_call` items in the history for a matching `call_id`. If we
+ * cannot resolve, fall back to `call_id` as the name - imperfect but
+ * preserves stream shape so the model sees *some* response.
+ */
+const isFunctionCallItem = (item: Item): item is FunctionCall => item.type === "function_call"
+
+const nameForCallId = (history: ReadonlyArray<Item>, call_id: string): Option.Option<string> =>
+  pipe(
+    history,
+    Arr.findFirst(
+      (item): item is FunctionCall => isFunctionCallItem(item) && item.call_id === call_id,
+    ),
+    Option.map((f) => f.name),
+  )
+
+/**
+ * Extract the Gemini-3 wire id we stashed in `providerData` on the way out.
+ * Schema-driven so the shape lives in one place; failure → `Option.none()`.
+ */
+const ProviderDataWithGeminiId = Schema.Struct({
+  gemini: Schema.Struct({ id: Schema.String }),
+})
+const decodeProviderId = Schema.decodeUnknownResult(ProviderDataWithGeminiId)
+
+const providerIdFor = (item: FunctionCall): Option.Option<string> =>
+  pipe(
+    decodeProviderId(item.providerData),
+    Result.match({
+      onSuccess: (d) => Option.some(d.gemini.id),
+      onFailure: () => Option.none<string>(),
+    }),
+  )
+
+const itemToContent =
+  (history: ReadonlyArray<Item>) =>
+  (item: Item): Result.Result<RequestContent, void> =>
+    Match.value(item).pipe(
+      Match.discriminatorsExhaustive("type")({
+        message: messageToContent,
+        function_call: (f) =>
+          Result.succeed({
+            role: "model" as const,
+            parts: [
+              {
+                functionCall: {
+                  ...Option.match(providerIdFor(f), {
+                    onSome: (id) => ({ id }),
+                    onNone: () => ({}),
+                  }),
+                  name: f.name,
+                  args: parsedArgs(f.arguments),
+                },
+              },
+            ],
+          }),
+        function_call_output: (o) =>
+          Result.succeed({
+            role: "user" as const,
+            parts: [
+              {
+                functionResponse: {
+                  name: Option.getOrElse(nameForCallId(history, o.call_id), () => o.call_id),
+                  response: parsedResponse(o.output),
+                },
+              },
+            ],
+          }),
+        reasoning: () => Result.failVoid,
+      }),
+    )
+
+// ---------------------------------------------------------------------------
+// Tool descriptors → Gemini `functionDeclarations`. Gemini accepts only a
+// strict OpenAPI 3.0 subset for `parameters`; strip JSON-Schema keys it
+// rejects (`$schema`, `$ref`, `additionalProperties`, `oneOf`,
+// `definitions`).
+// ---------------------------------------------------------------------------
+
+const UNSUPPORTED_SCHEMA_KEYS: ReadonlySet<string> = new Set([
+  "$schema",
+  "$ref",
+  "$defs",
+  "definitions",
+  "additionalProperties",
+  "oneOf",
+])
+
+const sanitizeSchema = (schema: unknown): unknown => {
+  if (Array.isArray(schema)) return schema.map(sanitizeSchema)
+  if (schema === null || typeof schema !== "object") return schema
+  return pipe(
+    Object.entries(schema as Record<string, unknown>),
+    Arr.filterMap(([k, v]) =>
+      UNSUPPORTED_SCHEMA_KEYS.has(k)
+        ? Result.failVoid
+        : Result.succeed([k, sanitizeSchema(v)] as const),
+    ),
+    Object.fromEntries,
+  )
+}
+
+const toolDescriptorsToTools = (tools: ReadonlyArray<ToolDescriptor>): ReadonlyArray<RequestTool> =>
+  tools.length === 0
+    ? []
+    : [
+        {
+          functionDeclarations: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: sanitizeSchema(t.inputSchema) as Record<string, unknown>,
+          })),
+        },
+      ]
+
 export const buildRequestBody = (
   history: ReadonlyArray<Item>,
   generationConfig: Option.Option<GenerationConfig>,
+  tools: ReadonlyArray<ToolDescriptor> = [],
 ): RequestBody => {
-  const msgs = messages(history)
-  const systemTexts = pipe(msgs, Arr.filterMap(systemMessageText))
-  const contents = pipe(msgs, Arr.filterMap(messageToContent))
+  const systemTexts = pipe(allMessages(history), Arr.filterMap(systemMessageText))
+  const contents = pipe(history, Arr.filterMap(itemToContent(history)))
+  const requestTools = toolDescriptorsToTools(tools)
   return {
     contents,
     ...(systemTexts.length > 0 && {
@@ -164,6 +351,10 @@ export const buildRequestBody = (
       onNone: () => ({}),
       onSome: (cfg) => ({ generationConfig: cfg }),
     }),
+    ...(requestTools.length > 0 && {
+      tools: requestTools,
+      toolConfig: { functionCallingConfig: { mode: "AUTO" as const } },
+    }),
   }
 }
 
@@ -180,9 +371,20 @@ const finishReasonToStop = (reason: Option.Option<string>): Turn["stop_reason"]
     onSome: (r) => (r === "MAX_TOKENS" ? ("max_tokens" as const) : ("stop" as const)),
   })
 
+export type AccumulatedFunctionCall = {
+  /** Synthesized id-or-name we surface as `call_id` on the canonical item. */
+  readonly callId: string
+  readonly name: string
+  /** Wire id from Gemini 3, when present - echoed back on `functionResponse`. */
+  readonly providerId: Option.Option<string>
+  /** Args as JSON-encoded string, mirroring `Items.FunctionCall.arguments`. */
+  readonly arguments: string
+}
+
 export type Accumulator = {
   readonly text: string
   readonly reasoning: string
+  readonly functionCalls: ReadonlyArray<AccumulatedFunctionCall>
   readonly finishReason: Option.Option<string>
   readonly usage: {
     readonly input_tokens?: number
@@ -196,18 +398,25 @@ export type Accumulator = {
 export const emptyAccumulator: Accumulator = {
   text: "",
   reasoning: "",
+  functionCalls: [],
   finishReason: Option.none(),
   usage: {},
 }
 
 /**
- * One part's worth of streamable text: either the model's answer
- * (`kind: "text"`) or chain-of-thought (`kind: "reasoning"`). Emitted
- * in wire order so consumers can interleave faithfully.
+ * One part's worth of streamable output. `text` and `reasoning` are
+ * incremental string deltas; `function_call` arrives whole-in-one-chunk
+ * (Gemini does not stream tool-call args).
  */
 export type ChunkPart =
   | { readonly kind: "text"; readonly text: string }
   | { readonly kind: "reasoning"; readonly text: string }
+  | {
+      readonly kind: "function_call"
+      readonly id: Option.Option<string>
+      readonly name: string
+      readonly args: unknown
+    }
 
 export type ChunkResult = {
   readonly accumulator: Accumulator
@@ -215,25 +424,40 @@ export type ChunkResult = {
   readonly finished: boolean
 }
 
+const isTextPart = (p: typeof Part.Type): p is typeof TextPart.Type => "text" in p
+
+const textToChunkParts = (p: typeof TextPart.Type): ReadonlyArray<ChunkPart> =>
+  p.text.length === 0 ? [] : [{ kind: p.thought === true ? "reasoning" : "text", text: p.text }]
+
+const functionCallToChunkParts = (p: WireFunctionCallPart): ReadonlyArray<ChunkPart> => [
+  {
+    kind: "function_call",
+    id: Option.fromNullishOr(p.functionCall.id),
+    name: p.functionCall.name,
+    args: p.functionCall.args ?? {},
+  },
+]
+
+const partToChunkParts = (p: typeof Part.Type): ReadonlyArray<ChunkPart> =>
+  isTextPart(p) ? textToChunkParts(p) : functionCallToChunkParts(p)
+
 const chunkParts = (chunk: WireChunk): ReadonlyArray<ChunkPart> =>
-  pipe(
-    chunk.candidates?.[0]?.content?.parts ?? [],
-    Arr.filterMap((p) =>
-      p.text.length === 0
-        ? Result.failVoid
-        : Result.succeed({
-            kind: p.thought === true ? ("reasoning" as const) : ("text" as const),
-            text: p.text,
-          }),
-    ),
-  )
+  pipe(chunk.candidates?.[0]?.content?.parts ?? [], Arr.flatMap(partToChunkParts))
 
-const sumByKind = (parts: ReadonlyArray<ChunkPart>, kind: ChunkPart["kind"]): string =>
+const sumStrings = (parts: ReadonlyArray<ChunkPart>, kind: "text" | "reasoning"): string =>
   pipe(
     parts,
     Arr.filterMap((p) => (p.kind === kind ? Result.succeed(p.text) : Result.failVoid)),
   ).join("")
 
+const collectFunctionCalls = (
+  parts: ReadonlyArray<ChunkPart>,
+): ReadonlyArray<Extract<ChunkPart, { kind: "function_call" }>> =>
+  pipe(
+    parts,
+    Arr.filterMap((p) => (p.kind === "function_call" ? Result.succeed(p) : Result.failVoid)),
+  )
+
 const mergeUsage = (
   prev: Accumulator["usage"],
   next: WireChunk["usageMetadata"],
@@ -255,6 +479,41 @@ const mergeUsage = (
         }),
       }
 
+/**
+ * Synthesize a stable `call_id` for a function call. Gemini 3 provides one
+ * via `functionCall.id`; older models do not, so we fall back to
+ * `<name>_<index>` based on prior calls' position in the accumulator.
+ */
+const synthesizeCallId = (
+  call: Extract<ChunkPart, { kind: "function_call" }>,
+  priorCalls: ReadonlyArray<AccumulatedFunctionCall>,
+): string =>
+  Option.match(call.id, {
+    onSome: (id) => id,
+    onNone: () => `${call.name}_${priorCalls.length}`,
+  })
+
+const chunkCallToAccumulated = (
+  prior: ReadonlyArray<AccumulatedFunctionCall>,
+  call: Extract<ChunkPart, { kind: "function_call" }>,
+): AccumulatedFunctionCall => ({
+  callId: synthesizeCallId(call, prior),
+  name: call.name,
+  providerId: call.id,
+  // `functionCallToChunkParts` already replaced null/undefined with `{}`,
+  // so `call.args` is always a JSON-encodable value here.
+  arguments: JSON.stringify(call.args),
+})
+
+const appendFunctionCalls = (
+  prior: ReadonlyArray<AccumulatedFunctionCall>,
+  fromChunk: ReadonlyArray<Extract<ChunkPart, { kind: "function_call" }>>,
+): ReadonlyArray<AccumulatedFunctionCall> =>
+  fromChunk.reduce<ReadonlyArray<AccumulatedFunctionCall>>(
+    (acc, call) => [...acc, chunkCallToAccumulated(acc, call)],
+    prior,
+  )
+
 export const ingestChunk = (acc: Accumulator, chunk: WireChunk): ChunkResult => {
   const parts = chunkParts(chunk)
   const finishReason = Option.fromNullishOr(chunk.candidates?.[0]?.finishReason)
@@ -262,27 +521,44 @@ export const ingestChunk = (acc: Accumulator, chunk: WireChunk): ChunkResult =>
     parts,
     finished: Option.isSome(finishReason),
     accumulator: {
-      text: acc.text + sumByKind(parts, "text"),
-      reasoning: acc.reasoning + sumByKind(parts, "reasoning"),
+      text: acc.text + sumStrings(parts, "text"),
+      reasoning: acc.reasoning + sumStrings(parts, "reasoning"),
+      functionCalls: appendFunctionCalls(acc.functionCalls, collectFunctionCalls(parts)),
       finishReason: Option.orElse(finishReason, () => acc.finishReason),
       usage: mergeUsage(acc.usage, chunk.usageMetadata),
     },
   }
 }
 
+const reasoningItems = (acc: Accumulator): ReadonlyArray<Item> =>
+  acc.reasoning.length > 0 ? [{ type: "reasoning", summary: acc.reasoning }] : []
+
+const assistantMessageItems = (acc: Accumulator): ReadonlyArray<Item> =>
+  acc.text.length === 0
+    ? []
+    : [
+        {
+          type: "message",
+          role: "assistant",
+          content: [{ type: "output_text", text: acc.text }],
+        },
+      ]
+
+const functionCallItems = (acc: Accumulator): ReadonlyArray<Item> =>
+  pipe(
+    acc.functionCalls,
+    Arr.map((c) => ({
+      type: "function_call" as const,
+      call_id: c.callId,
+      name: c.name,
+      arguments: c.arguments,
+      ...(Option.isSome(c.providerId) && { providerData: { gemini: { id: c.providerId.value } } }),
+    })),
+  )
+
 export const accumulatorToTurn = (acc: Accumulator): Turn => ({
-  stop_reason: finishReasonToStop(acc.finishReason),
+  stop_reason:
+    acc.functionCalls.length > 0 ? ("tool_calls" as const) : finishReasonToStop(acc.finishReason),
   usage: { ...acc.usage },
-  items: [
-    ...(acc.reasoning.length > 0 ? [{ type: "reasoning" as const, summary: acc.reasoning }] : []),
-    ...(acc.text.length === 0
-      ? []
-      : [
-          {
-            type: "message" as const,
-            role: "assistant" as const,
-            content: [{ type: "output_text" as const, text: acc.text }],
-          },
-        ]),
-  ],
+  items: [...reasoningItems(acc), ...assistantMessageItems(acc), ...functionCallItems(acc)],
 })

package/src/geminiSpeechCodec.test.ts

@@ -0,0 +1,56 @@
+import { Effect, Encoding } from "effect"
+import { describe, expect, it } from "vitest"
+import type { AudioSource } from "@effect-uai/core/Audio"
+import { audioSourceToInlineData, wrapPcmAsWav } from "./geminiSpeechCodec.js"
+
+describe("audioSourceToInlineData", () => {
+  it("encodes a `bytes` source to base64 with its MIME type", async () => {
+    const original = new Uint8Array([0xde, 0xad, 0xbe, 0xef])
+    const source: AudioSource = { _tag: "bytes", bytes: original, mimeType: "audio/wav" }
+    const inline = await Effect.runPromise(audioSourceToInlineData(source))
+    expect(inline.mimeType).toBe("audio/wav")
+    expect(inline.data).toBe(Encoding.encodeBase64(original))
+  })
+
+  it("passes a `base64` source through unchanged", async () => {
+    const b64 = Encoding.encodeBase64(new Uint8Array([1, 2, 3]))
+    const source: AudioSource = { _tag: "base64", base64: b64, mimeType: "audio/mp3" }
+    const inline = await Effect.runPromise(audioSourceToInlineData(source))
+    expect(inline.mimeType).toBe("audio/mp3")
+    expect(inline.data).toBe(b64)
+  })
+
+  it("fails InvalidRequest for a URL source", async () => {
+    const source: AudioSource = { _tag: "url", url: "https://x/y.mp3", mimeType: "audio/mp3" }
+    const exit = await Effect.runPromiseExit(audioSourceToInlineData(source))
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") {
+      expect(JSON.stringify(exit.cause)).toContain("InvalidRequest")
+      expect(JSON.stringify(exit.cause)).toContain("Files API")
+    }
+  })
+})
+
+describe("wrapPcmAsWav", () => {
+  it("produces a 44-byte RIFF/WAVE header for 16-bit mono PCM at 24 kHz", () => {
+    const pcm = new Uint8Array([0x00, 0x01, 0x00, 0x02])
+    const wav = wrapPcmAsWav(pcm, 24000, 1, 16)
+    expect(wav.length).toBe(44 + pcm.length)
+    const ascii = (start: number, len: number) =>
+      String.fromCharCode(...Array.from(wav.slice(start, start + len)))
+    expect(ascii(0, 4)).toBe("RIFF")
+    expect(ascii(8, 4)).toBe("WAVE")
+    expect(ascii(12, 4)).toBe("fmt ")
+    expect(ascii(36, 4)).toBe("data")
+    // RIFF chunk size = total - 8
+    const view = new DataView(wav.buffer)
+    expect(view.getUint32(4, true)).toBe(wav.length - 8)
+    expect(view.getUint16(20, true)).toBe(1) // PCM
+    expect(view.getUint16(22, true)).toBe(1) // mono
+    expect(view.getUint32(24, true)).toBe(24000) // sample rate
+    expect(view.getUint16(34, true)).toBe(16) // bits per sample
+    expect(view.getUint32(40, true)).toBe(pcm.length) // data size
+    // Payload preserved
+    expect(Array.from(wav.slice(44))).toEqual(Array.from(pcm))
+  })
+})

package/src/geminiSpeechCodec.ts

@@ -0,0 +1,137 @@
+import { Effect, Encoding, Match, Result } from "effect"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioSource } from "@effect-uai/core/Audio"
+
+/**
+ * Shared codec helpers for Gemini speech endpoints. The TTS and STT
+ * variants both ride on `:generateContent`, so the audio-in / audio-out
+ * shapes are siblings.
+ */
+
+const urlNotSupported: AiError.AiError = new AiError.InvalidRequest({
+  provider: "gemini",
+  param: "audio",
+  raw: 'Gemini inline audio does not accept URL sources. Either fetch the URL yourself and pass `{ _tag: "bytes", bytes, mimeType }`, or upload via the Files API and pass a `fileData` URI (not yet wired here).',
+})
+
+/** Wire shape for an inline-audio part on `generateContent`. */
+export type InlineAudioData = {
+  readonly mimeType: string
+  readonly data: string
+}
+
+/**
+ * Encode any `AudioSource` into the `inlineData` shape expected by
+ * Gemini's `generateContent`. URL variants are rejected with
+ * `InvalidRequest` — Files API upload is a separate flow.
+ *
+ * Caller is responsible for keeping the total request body under
+ * 20 MB. Beyond that, Gemini's Files API is the only path.
+ */
+export const audioSourceToInlineData: (
+  audio: AudioSource,
+) => Effect.Effect<InlineAudioData, AiError.AiError> = Match.type<AudioSource>().pipe(
+  Match.tag("bytes", (a) =>
+    Effect.succeed<InlineAudioData>({
+      mimeType: a.mimeType,
+      data: Encoding.encodeBase64(a.bytes),
+    }),
+  ),
+  Match.tag("base64", (a) =>
+    Effect.succeed<InlineAudioData>({ mimeType: a.mimeType, data: a.base64 }),
+  ),
+  Match.tag("url", () => Effect.fail(urlNotSupported)),
+  Match.exhaustive,
+)
+
+/** Decode a base64-encoded audio payload into bytes. */
+export const decodeBase64Audio = (b64: string): Effect.Effect<Uint8Array, AiError.AiError> =>
+  Result.match(Encoding.decodeBase64(b64), {
+    onSuccess: Effect.succeed,
+    onFailure: (cause) =>
+      Effect.fail(new AiError.InvalidRequest({ provider: "gemini", param: "audio", raw: cause })),
+  })
+
+/**
+ * Wrap a raw 16-bit signed little-endian PCM buffer in a standard 44-byte
+ * RIFF/WAVE header. Gemini TTS returns PCM-only — for playback or for
+ * round-tripping into Gemini transcription (which accepts wav, not raw
+ * PCM), the bytes need a container.
+ */
+export const wrapPcmAsWav = (
+  pcm: Uint8Array,
+  sampleRate: number,
+  channels: number,
+  bitsPerSample = 16,
+): Uint8Array => {
+  const dataSize = pcm.length
+  const blockAlign = (channels * bitsPerSample) / 8
+  const byteRate = sampleRate * blockAlign
+  const totalSize = 44 + dataSize
+  const buffer = new ArrayBuffer(totalSize)
+  const view = new DataView(buffer)
+  const writeAscii = (offset: number, s: string): void => {
+    for (let i = 0; i < s.length; i++) view.setUint8(offset + i, s.charCodeAt(i))
+  }
+  writeAscii(0, "RIFF")
+  view.setUint32(4, totalSize - 8, true)
+  writeAscii(8, "WAVE")
+  writeAscii(12, "fmt ")
+  view.setUint32(16, 16, true)
+  view.setUint16(20, 1, true)
+  view.setUint16(22, channels, true)
+  view.setUint32(24, sampleRate, true)
+  view.setUint32(28, byteRate, true)
+  view.setUint16(32, blockAlign, true)
+  view.setUint16(34, bitsPerSample, true)
+  writeAscii(36, "data")
+  view.setUint32(40, dataSize, true)
+  new Uint8Array(buffer, 44, dataSize).set(pcm)
+  return new Uint8Array(buffer)
+}
+
+/**
+ * HTTP status → typed `AiError`. Shared between synthesizer and
+ * transcriber.
+ */
+export const httpStatusError: (status: number, body: string) => AiError.AiError = (status, body) =>
+  Match.value(status).pipe(
+    Match.when(
+      429,
+      (): AiError.AiError => new AiError.RateLimited({ provider: "gemini", raw: body }),
+    ),
+    Match.whenOr(
+      408,
+      504,
+      (): AiError.AiError => new AiError.Timeout({ provider: "gemini", raw: body }),
+    ),
+    Match.when(
+      401,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "gemini", subtype: "auth", raw: body }),
+    ),
+    Match.when(
+      403,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "gemini", subtype: "permission", raw: body }),
+    ),
+    Match.when(
+      402,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "gemini", subtype: "billing", raw: body }),
+    ),
+    Match.when(
+      413,
+      (): AiError.AiError => new AiError.ContextLengthExceeded({ provider: "gemini", raw: body }),
+    ),
+    Match.when(
+      (n) => n >= 500,
+      (n): AiError.AiError => new AiError.Unavailable({ provider: "gemini", status: n, raw: body }),
+    ),
+    Match.orElse(
+      (): AiError.AiError => new AiError.InvalidRequest({ provider: "gemini", raw: body }),
+    ),
+  )
+
+export const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "gemini", raw: cause })

package/src/index.ts

@@ -1,4 +1,7 @@
 export * as Gemini from "./Gemini.js"
 export * as GeminiEmbedding from "./GeminiEmbedding.js"
+export * as GeminiSynthesizer from "./GeminiSynthesizer.js"
+export * as GeminiTranscriber from "./GeminiTranscriber.js"
+export * as LyriaGenerator from "./LyriaGenerator.js"
 export * as codec from "./codec.js"
 export * from "./models.js"