@effect-uai/google 0.5.2 → 0.7.0

package/src/LyriaGenerator.test.ts

@@ -1,81 +1,17 @@
-import { Effect, Layer, Redacted, Stream } from "effect"
+import { Duration, Effect, Layer, Redacted, Stream } from "effect"
 import { FetchHttpClient } from "effect/unstable/http"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type * as AiError from "@effect-uai/core/AiError"
-import * as MusicGenerator from "@effect-uai/core/MusicGenerator"
+import type { GenerateResult } from "@effect-uai/core/Music"
 import { promptsInput } from "@effect-uai/core/Music"
+import * as MusicGenerator from "@effect-uai/core/MusicGenerator"
 import * as LyriaGenerator from "./LyriaGenerator.js"
 
 const cfg: LyriaGenerator.Config = { apiKey: Redacted.make("test-key") }
 // FetchHttpClient is required for `make`, but these tests only exercise the
-// compile-time gating and runtime Unsupported branches — no real HTTP is made.
+// compile-time gating and runtime Unsupported branches, no real HTTP is made.
 const live = Layer.provide(LyriaGenerator.layer(cfg), FetchHttpClient.layer)
 
-describe("buildPrompt", () => {
-  it("returns a plain string when prompts is a string", () => {
-    const out = LyriaGenerator.buildPrompt({
-      model: "lyria-3-clip-preview",
-      prompts: "upbeat indie pop",
-    })
-    expect(out).toBe("upbeat indie pop")
-  })
-
-  it("joins weighted prompts with weight annotations", () => {
-    const out = LyriaGenerator.buildPrompt({
-      model: "lyria-3-clip-preview",
-      prompts: [
-        { text: "minimal techno", weight: 1.0 },
-        { text: "1980s synthwave", weight: 0.3 },
-      ],
-    })
-    expect(out).toContain("minimal techno")
-    expect(out).toContain("1980s synthwave (weight 0.3)")
-  })
-
-  it("omits the weight annotation for weight === 1", () => {
-    const out = LyriaGenerator.buildPrompt({
-      model: "lyria-3-clip-preview",
-      prompts: [{ text: "ambient", weight: 1 }],
-    })
-    expect(out).toBe("ambient")
-  })
-
-  it("splices in bpm, scale, duration, and instrumental hints", () => {
-    const out = LyriaGenerator.buildPrompt({
-      model: "lyria-3-clip-preview",
-      prompts: "house",
-      bpm: 124,
-      scale: "C_MAJOR",
-      durationSeconds: 30,
-      instrumental: true,
-    })
-    expect(out).toContain("Instrumental only")
-    expect(out).toContain("BPM: 124")
-    expect(out).toContain("Key/scale: C_MAJOR")
-    expect(out).toContain("Target duration: 30s")
-  })
-
-  it("appends a lyrics block when lyrics is set and instrumental is not true", () => {
-    const out = LyriaGenerator.buildPrompt({
-      model: "lyria-3-clip-preview",
-      prompts: "indie rock",
-      lyrics: "[Verse]\nhello world",
-    })
-    expect(out).toContain("Lyrics:")
-    expect(out).toContain("[Verse]")
-  })
-
-  it("drops the lyrics block when instrumental is true", () => {
-    const out = LyriaGenerator.buildPrompt({
-      model: "lyria-3-clip-preview",
-      prompts: "indie rock",
-      lyrics: "[Verse]\nhello world",
-      instrumental: true,
-    })
-    expect(out).not.toContain("Lyrics:")
-  })
-})
-
 describe("containerToMimeType", () => {
   it("maps mp3 and wav", async () => {
     expect(await Effect.runPromise(LyriaGenerator.containerToMimeType("mp3"))).toBe("audio/mp3")
@@ -115,7 +51,7 @@ describe("LyriaGenerator capability guards (runtime)", () => {
       Stream.runDrain(
         s.streamGenerationFrom(Stream.fromIterable([promptsInput([{ text: "x" }])]), {
           model: "lyria-3-clip-preview",
-          prompts: "",
+          prompt: "",
         }),
       ),
     )
@@ -131,32 +67,52 @@ describe("LyriaGenerator capability guards (runtime)", () => {
 describe("LyriaGenerator Layer (compile-time)", () => {
   it("leaves `MusicInteractiveSession` unsatisfied when using `streamGenerationFrom` against this Layer", () => {
     const inputs = Stream.fromIterable([promptsInput([{ text: "techno" }])])
-    const audio = inputs.pipe(
+    const events = inputs.pipe(
       MusicGenerator.streamGenerationFrom({
         model: "lyria-3-clip-preview",
-        prompts: "",
+        prompt: "",
       }),
     )
-    const provided = Stream.runDrain(audio).pipe(Effect.provide(live))
+    const provided = Stream.runDrain(events).pipe(Effect.provide(live))
     expectTypeOf(provided).toEqualTypeOf<
       Effect.Effect<void, AiError.AiError, MusicGenerator.MusicInteractiveSession>
     >()
   })
 
-  it("sync `generate` and chunked `streamGeneration` require no marker", () => {
+  it("sync `generate` returns GenerateResult and requires no marker", () => {
     const gen = MusicGenerator.generate({
       model: "lyria-3-clip-preview",
-      prompts: "ambient",
+      prompt: "ambient",
     }).pipe(Effect.provide(live))
-    expectTypeOf(gen).toEqualTypeOf<
-      Effect.Effect<import("@effect-uai/core/Music").MusicResult, AiError.AiError, never>
-    >()
+    expectTypeOf(gen).toEqualTypeOf<Effect.Effect<GenerateResult, AiError.AiError, never>>()
+  })
+
+  it("chunked `streamGeneration` requires no marker", () => {
     const _stream = Stream.runCollect(
       MusicGenerator.streamGeneration({
         model: "lyria-3-clip-preview",
-        prompts: "ambient",
+        prompt: "ambient",
       }),
     ).pipe(Effect.provide(live))
     expect(_stream).toBeDefined()
   })
+
+  it("Lyria-typed request accepts no `instrumental` field", () => {
+    const _req: LyriaGenerator.LyriaGenerateRequest = {
+      model: "lyria-3-clip-preview",
+      prompt: "ambient",
+      // @ts-expect-error: instrumental was removed from LyriaGenerateRequest in v0.7
+      instrumental: true,
+    }
+    expect(_req).toBeDefined()
+  })
+
+  it("Common request supports `duration: Duration.Duration`", () => {
+    const _req: MusicGenerator.CommonGenerateMusicRequest = {
+      model: "lyria-3-clip-preview",
+      prompt: "ambient",
+      duration: Duration.seconds(30),
+    }
+    expect(_req).toBeDefined()
+  })
 })

package/src/LyriaGenerator.ts

@@ -1,11 +1,10 @@
 import {
-  Array as Arr,
   Context,
+  Duration,
   Effect,
   Encoding,
   Layer,
   Match,
-  Option,
   Redacted,
   Result,
   Schema,
@@ -14,13 +13,16 @@ import {
 import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import * as AiError from "@effect-uai/core/AiError"
 import type { AudioChunk, AudioFormat } from "@effect-uai/core/Audio"
+import { warnDroppedWhen } from "@effect-uai/core/Capabilities"
 import type {
   CommonGenerateMusicRequest,
   CommonStreamGenerateMusicRequest,
+  GenerateResult,
   MusicResult,
   MusicSessionInput,
-  WeightedPrompt,
+  MusicStreamEvent,
 } from "@effect-uai/core/Music"
+import { singleVariant } from "@effect-uai/core/Music"
 import { MusicGenerator, type MusicGeneratorService } from "@effect-uai/core/MusicGenerator"
 import type { LyriaModel } from "./models.js"
 
@@ -29,25 +31,34 @@ import type { LyriaModel } from "./models.js"
 // ---------------------------------------------------------------------------
 
 /**
- * Lyria-typed generate request. Narrows `model` to `LyriaModel`. The
- * Lyria sync API (`generateContent`) accepts only `audio/mp3` and
- * `audio/wav` output; `bpm`, `scale`, `instrumental` etc. on the
- * `CommonGenerateMusicRequest` are flattened into the prompt text
- * because the public API does not expose them as structured fields.
+ * Lyria-typed generate request. Narrows `model` to `LyriaModel`.
+ *
+ * Lyria 3 sync `generateContent` has no structured wire fields for
+ * `lyrics` / `duration` / `seed` / `instrumental` / `bpm` / `scale` /
+ * etc. Those fields on the Common request are logged as
+ * dropped-bucket-2 hints; the adapter never rewrites or augments the
+ * caller's prompt on their behalf. If you want lyrics or vocal
+ * suppression, include them in your `prompt` text yourself.
+ *
+ * Output format: only `audio/mp3` and `audio/wav` are accepted; other
+ * containers fail `Unsupported`. The Clip model variant is fixed at
+ * `audio/mp3`.
  */
 export type LyriaGenerateRequest = Omit<CommonGenerateMusicRequest, "model"> & {
   readonly model: LyriaModel
 }
 
 export type LyriaGeneratorService = {
-  readonly generate: (request: LyriaGenerateRequest) => Effect.Effect<MusicResult, AiError.AiError>
+  readonly generate: (
+    request: LyriaGenerateRequest,
+  ) => Effect.Effect<GenerateResult, AiError.AiError>
   readonly streamGeneration: (
     request: LyriaGenerateRequest,
   ) => Stream.Stream<AudioChunk, AiError.AiError>
   readonly streamGenerationFrom: <E, R>(
     input: Stream.Stream<MusicSessionInput, E, R>,
     request: CommonStreamGenerateMusicRequest,
-  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R>
+  ) => Stream.Stream<MusicStreamEvent, AiError.AiError | E, R>
 }
 
 export class LyriaGenerator extends Context.Service<LyriaGenerator, LyriaGeneratorService>()(
@@ -60,7 +71,7 @@ export type Config = {
 }
 
 // ---------------------------------------------------------------------------
-// Codec — request → prompt text + response_format
+// Codec: AudioFormat → Lyria mimeType
 // ---------------------------------------------------------------------------
 
 export type LyriaResponseMimeType = "audio/mp3" | "audio/wav"
@@ -85,10 +96,10 @@ export const containerToMimeType: (
 )
 
 /**
- * Is this a Lyria 3 Clip model variant? Clip is fixed at 30 s MP3 — it
+ * Is this a Lyria 3 Clip model variant? Clip is fixed at 30 s MP3, it
  * does not accept a `responseFormat` on `generationConfig` (the live
- * API rejects unknown fields, despite what the docs imply). Pro
- * accepts the documented `responseFormat` knob.
+ * API rejects unknown fields). Pro accepts the documented
+ * `responseFormat` knob.
  */
 const isClipModel = (model: string): boolean => model.includes("clip")
 
@@ -110,38 +121,51 @@ export const realizedFormat: (mime: LyriaResponseMimeType) => AudioFormat =
     Match.exhaustive,
   )
 
+// ---------------------------------------------------------------------------
+// Bucket-2 warn-and-drop for Common fields Lyria 3 can't honor
+// ---------------------------------------------------------------------------
+
 /**
- * Collapse `prompts | WeightedPrompt[]` into a single prompt string and
- * splice in non-structural hints (`lyrics`, `bpm`, `scale`,
- * `instrumental`, `durationSeconds`). The Lyria 3 sync API only takes
- * one text part — every condition lives inline.
+ * Warn (don't fail) when the caller passed Common fields Lyria 3 has
+ * no wire field for. Bucket-2 per capabilities policy: provider has
+ * no structured interpretation; the output is still valid music, just
+ * less aligned with the caller's hint. We never embed these into the
+ * prompt on the caller's behalf, prompt construction is the
+ * developer's job.
  */
-export const buildPrompt = (request: CommonGenerateMusicRequest): string => {
-  const promptText = Match.value(request.prompts).pipe(
-    Match.when(Match.string, (s) => s),
-    Match.orElse((ws: ReadonlyArray<WeightedPrompt>) =>
-      Arr.map(ws, (w) =>
-        w.weight !== undefined && w.weight !== 1 ? `${w.text} (weight ${w.weight})` : w.text,
-      ).join(". "),
-    ),
+const warnDroppedHints = (request: LyriaGenerateRequest): Effect.Effect<void> =>
+  Effect.all(
+    [
+      warnDroppedWhen(request.lyrics, {
+        provider: "lyria",
+        capability: "lyrics",
+        field: "lyrics",
+        reason:
+          "Lyria 3 sync has no `lyrics` wire field. If you want vocals to follow specific lyrics, embed them in your prompt yourself (e.g. with `[Verse]` / `[Chorus]` tags).",
+      }),
+      warnDroppedWhen(
+        request.duration !== undefined ? Duration.toMillis(request.duration) : undefined,
+        {
+          provider: "lyria",
+          capability: "duration",
+          field: "duration",
+          reason:
+            "Lyria 3 clip is fixed at 30 s; pro derives duration from prompt content. There is no wire field for duration. If you want to steer length, mention it in your prompt.",
+        },
+      ),
+      warnDroppedWhen(request.seed, {
+        provider: "lyria",
+        capability: "seed",
+        field: "seed",
+        reason:
+          "Lyria 3 (Gemini surface) does not expose a seed parameter. Output is non-deterministic across identical prompts. Use Lyria 2 (Vertex) for seeded generation.",
+      }),
+    ],
+    { discard: true },
   )
-  const hints = Arr.getSomes([
-    request.instrumental === true ? Option.some("Instrumental only — no vocals.") : Option.none(),
-    request.bpm !== undefined ? Option.some(`BPM: ${request.bpm}.`) : Option.none(),
-    request.scale !== undefined ? Option.some(`Key/scale: ${request.scale}.`) : Option.none(),
-    request.durationSeconds !== undefined
-      ? Option.some(`Target duration: ${request.durationSeconds}s.`)
-      : Option.none(),
-  ])
-  const lyricsBlock =
-    request.lyrics !== undefined && request.instrumental !== true
-      ? `\n\nLyrics:\n${request.lyrics}`
-      : ""
-  return [promptText, ...hints].join(" ") + lyricsBlock
-}
 
 // ---------------------------------------------------------------------------
-// Wire response schema — just enough to find audio + optional lyrics text
+// Wire response schema
 // ---------------------------------------------------------------------------
 
 const InlineData = Schema.Struct({
@@ -245,26 +269,23 @@ const generateImpl =
   (cfg: Config) =>
   (
     request: LyriaGenerateRequest,
-  ): Effect.Effect<MusicResult, AiError.AiError, HttpClient.HttpClient> =>
+  ): Effect.Effect<GenerateResult, AiError.AiError, HttpClient.HttpClient> =>
     Effect.gen(function* () {
       const client = yield* HttpClient.HttpClient
       const requestedContainer = (request.outputFormat?.container ??
         "mp3") satisfies AudioFormat["container"]
-      const mimeType = yield* containerToMimeType(requestedContainer)
-      // Clip is fixed 30 s mp3 — reject wav up front rather than sending
-      // a `responseFormat` that the live API ignores or rejects.
-      if (isClipModel(request.model) && mimeType === "audio/wav") {
-        return yield* new AiError.Unsupported({
-          provider: "lyria",
-          capability: "outputFormat",
-          reason: `lyria-3-clip-preview is fixed at audio/mp3. Use lyria-3-pro-preview for audio/wav output.`,
-        })
-      }
-      const promptText = buildPrompt(request)
+      const requestedMime = yield* containerToMimeType(requestedContainer)
+      // lyria-3-clip-preview has no `responseFormat` wire field and always
+      // emits mp3, so there is no format to send and no 400 to surface. Rather
+      // than keep a per-model table that rejects `wav`, report the format the
+      // model actually produces (mp3) so the result is never mislabeled.
+      // lyria-3-pro honours the requested container.
+      const mimeType = isClipModel(request.model) ? ("audio/mp3" as const) : requestedMime
+      yield* warnDroppedHints(request)
       const body = isClipModel(request.model)
-        ? { contents: [{ parts: [{ text: promptText }] }] }
+        ? { contents: [{ parts: [{ text: request.prompt }] }] }
         : {
-            contents: [{ parts: [{ text: promptText }] }],
+            contents: [{ parts: [{ text: request.prompt }] }],
             generationConfig: {
               responseModalities: ["AUDIO", "TEXT"],
               responseFormat: { audio: { mimeType } },
@@ -290,10 +311,6 @@ const generateImpl =
       )
       const { inline, text } = extractParts(wire)
       if (inline === undefined) {
-        // No audio came back. Most common cause: Lyria filtered the prompt
-        // (named-artist references, copyrighted lyrics, etc.). Surface the
-        // full response body — text parts, finish reasons, prompt-feedback
-        // blocks — so the caller can see why.
         return yield* new AiError.GenerationFailed({
           provider: "lyria",
           raw: {
@@ -305,12 +322,13 @@ const generateImpl =
         })
       }
       const bytes = yield* decodeBase64ToBytes(inline.data)
-      return {
-        format: realizedFormat(mimeType),
-        bytes,
+      const result: MusicResult = {
+        audio: { format: realizedFormat(mimeType), bytes },
+        provider: "lyria",
         ...(text !== undefined && { lyrics: text }),
-        watermark: { kind: "synthid" },
-      } satisfies MusicResult
+        watermark: "synthid",
+      }
+      return singleVariant(result)
     })
 
 const streamGenerationImpl =
@@ -320,22 +338,22 @@ const streamGenerationImpl =
   ): Stream.Stream<AudioChunk, AiError.AiError, HttpClient.HttpClient> =>
     Stream.unwrap(
       Effect.map(generateImpl(cfg)(request), (result) =>
-        Stream.succeed<AudioChunk>({ bytes: result.bytes }),
+        Stream.succeed<AudioChunk>({ bytes: result.primary.audio.bytes }),
       ),
     )
 
 /**
- * Lyria 3 sync has no bidirectional session at the wire level — that's
- * Lyria RealTime (Phase 1b, separate Layer). The provider Layer here
- * also does NOT register `MusicInteractiveSession`, so callers using
+ * Lyria 3 sync has no bidirectional session at the wire level, that's
+ * Lyria RealTime (separate Layer). The provider Layer here also does
+ * NOT register `MusicInteractiveSession`, so callers using
  * `MusicGenerator.streamGenerationFrom` against only this Layer get a
  * compile-time error before this runtime fallback ever fires.
  */
 const streamGenerationFromUnsupported = <E, R>(
   _input: Stream.Stream<MusicSessionInput, E, R>,
   _request: CommonStreamGenerateMusicRequest,
-): Stream.Stream<AudioChunk, AiError.AiError | E, R> => {
-  const fail: Stream.Stream<AudioChunk, AiError.AiError | E, R> = Stream.fail(
+): Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> => {
+  const fail: Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> = Stream.fail(
     new AiError.Unsupported({
       provider: "lyria",
       capability: "streamGenerationFrom",
@@ -365,7 +383,7 @@ export const make = (
  * Layer that registers both the provider-specific `LyriaGenerator` tag
  * and the generic `MusicGenerator` tag.
  *
- * Does NOT register the `MusicInteractiveSession` capability marker —
+ * Does NOT register the `MusicInteractiveSession` capability marker,
  * Lyria 3 sync has no bidirectional session at the wire level. Code
  * calling `MusicGenerator.streamGenerationFrom` will fail to typecheck
  * against this Layer alone, which is the intended UX.
@@ -380,9 +398,10 @@ export const layer = (
       Effect.map(
         make(cfg),
         (s): MusicGeneratorService => ({
-          generate: (req: CommonGenerateMusicRequest) => s.generate(req as LyriaGenerateRequest),
+          generate: (req: CommonGenerateMusicRequest) =>
+            s.generate({ ...req, model: req.model as LyriaModel }),
           streamGeneration: (req: CommonStreamGenerateMusicRequest) =>
-            s.streamGeneration(req as LyriaGenerateRequest),
+            s.streamGeneration({ ...req, model: req.model as LyriaModel }),
           streamGenerationFrom: s.streamGenerationFrom,
         }),
       ),

package/src/codec.ts

@@ -1,7 +1,14 @@
 import { Array as Arr, Encoding, Match, Option, Result, Schema, pipe } from "effect"
-import type { ContentBlock, FunctionCall, InputImage, Item, Message } from "@effect-uai/core/Items"
+import type {
+  ContentBlock,
+  ToolCall,
+  InputImage,
+  HistoryItem,
+  Message,
+} from "@effect-uai/core/Items"
 import type { ToolDescriptor } from "@effect-uai/core/Tool"
 import type { Turn } from "@effect-uai/core/Turn"
+import type { CommonRequest } from "@effect-uai/core/LanguageModel"
 
 // ---------------------------------------------------------------------------
 // Wire schemas - the subset of Gemini's streamGenerateContent payload we
@@ -183,7 +190,7 @@ const systemMessageText = (message: Message): Result.Result<string, void> => {
   return text.length === 0 ? Result.failVoid : Result.succeed(text)
 }
 
-const allMessages = (history: ReadonlyArray<Item>): ReadonlyArray<Message> =>
+const allMessages = (history: ReadonlyArray<HistoryItem>): ReadonlyArray<Message> =>
   pipe(
     history,
     Arr.filterMap((item) => (item.type === "message" ? Result.succeed(item) : Result.failVoid)),
@@ -192,7 +199,7 @@ const allMessages = (history: ReadonlyArray<Item>): ReadonlyArray<Message> =>
 // ---------------------------------------------------------------------------
 // Function-call round-trip
 //
-// `FunctionCall.arguments` and `FunctionCallOutput.output` are JSON-encoded
+// `ToolCall.arguments` and `ToolCallOutput.output` are JSON-encoded
 // strings; Gemini's `functionCall.args` and `functionResponse.response`
 // expect parsed JSON *objects*. Decode via Schema:
 //   - object payload → use as-is
@@ -218,20 +225,21 @@ const parsedArgs = parsedJsonObject(() => ({}))
 const parsedResponse = parsedJsonObject((raw) => ({ output: raw }))
 
 /**
- * `FunctionCallOutput` only carries `call_id`; Gemini's `functionResponse`
+ * `ToolCallOutput` 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 isFunctionCallItem = (item: HistoryItem): item is ToolCall => item.type === "function_call"
 
-const nameForCallId = (history: ReadonlyArray<Item>, call_id: string): Option.Option<string> =>
+const nameForCallId = (
+  history: ReadonlyArray<HistoryItem>,
+  call_id: string,
+): Option.Option<string> =>
   pipe(
     history,
-    Arr.findFirst(
-      (item): item is FunctionCall => isFunctionCallItem(item) && item.call_id === call_id,
-    ),
+    Arr.findFirst((item): item is ToolCall => isFunctionCallItem(item) && item.call_id === call_id),
     Option.map((f) => f.name),
   )
 
@@ -244,7 +252,7 @@ const ProviderDataWithGeminiId = Schema.Struct({
 })
 const decodeProviderId = Schema.decodeUnknownResult(ProviderDataWithGeminiId)
 
-const providerIdFor = (item: FunctionCall): Option.Option<string> =>
+const providerIdFor = (item: ToolCall): Option.Option<string> =>
   pipe(
     decodeProviderId(item.providerData),
     Result.match({
@@ -254,8 +262,8 @@ const providerIdFor = (item: FunctionCall): Option.Option<string> =>
   )
 
 const itemToContent =
-  (history: ReadonlyArray<Item>) =>
-  (item: Item): Result.Result<RequestContent, void> =>
+  (history: ReadonlyArray<HistoryItem>) =>
+  (item: HistoryItem): Result.Result<RequestContent, void> =>
     Match.value(item).pipe(
       Match.discriminatorsExhaustive("type")({
         message: messageToContent,
@@ -334,10 +342,39 @@ const toolDescriptorsToTools = (tools: ReadonlyArray<ToolDescriptor>): ReadonlyA
         },
       ]
 
+/**
+ * Map our cross-provider `toolChoice` onto Gemini's `functionCallingConfig`.
+ * Gemini honours the same three modes plus a function allow-list, so the
+ * choice is mapped, not dropped. `undefined` keeps the API default (`AUTO`).
+ */
+const toolChoiceToFunctionCallingConfig = (
+  toolChoice: CommonRequest["toolChoice"],
+): RequestToolConfig["functionCallingConfig"] =>
+  Match.value(toolChoice ?? "auto").pipe(
+    Match.when("auto", () => ({ mode: "AUTO" as const })),
+    Match.when("required", () => ({ mode: "ANY" as const })),
+    Match.when("none", () => ({ mode: "NONE" as const })),
+    Match.orElse((tc) => ({ mode: "ANY" as const, allowedFunctionNames: [tc.name] })),
+  )
+
+/**
+ * URL-form images need Gemini's Files API (upload, then `fileData`); we
+ * don't pre-upload, so such a part would otherwise vanish from the request.
+ * The caller fails the request with `Unsupported` instead of silently
+ * dropping the image.
+ */
+export const hasUrlImageSource = (history: ReadonlyArray<HistoryItem>): boolean =>
+  history.some(
+    (item) =>
+      item.type === "message" &&
+      item.content.some((b) => b.type === "input_image" && b.source._tag === "url"),
+  )
+
 export const buildRequestBody = (
-  history: ReadonlyArray<Item>,
+  history: ReadonlyArray<HistoryItem>,
   generationConfig: Option.Option<GenerationConfig>,
   tools: ReadonlyArray<ToolDescriptor> = [],
+  toolChoice: CommonRequest["toolChoice"] = undefined,
 ): RequestBody => {
   const systemTexts = pipe(allMessages(history), Arr.filterMap(systemMessageText))
   const contents = pipe(history, Arr.filterMap(itemToContent(history)))
@@ -353,7 +390,7 @@ export const buildRequestBody = (
     }),
     ...(requestTools.length > 0 && {
       tools: requestTools,
-      toolConfig: { functionCallingConfig: { mode: "AUTO" as const } },
+      toolConfig: { functionCallingConfig: toolChoiceToFunctionCallingConfig(toolChoice) },
     }),
   }
 }
@@ -377,7 +414,7 @@ export type AccumulatedFunctionCall = {
   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`. */
+  /** Args as JSON-encoded string, mirroring `Items.ToolCall.arguments`. */
   readonly arguments: string
 }
 
@@ -530,10 +567,10 @@ export const ingestChunk = (acc: Accumulator, chunk: WireChunk): ChunkResult =>
   }
 }
 
-const reasoningItems = (acc: Accumulator): ReadonlyArray<Item> =>
+const reasoningItems = (acc: Accumulator): ReadonlyArray<HistoryItem> =>
   acc.reasoning.length > 0 ? [{ type: "reasoning", summary: acc.reasoning }] : []
 
-const assistantMessageItems = (acc: Accumulator): ReadonlyArray<Item> =>
+const assistantMessageItems = (acc: Accumulator): ReadonlyArray<HistoryItem> =>
   acc.text.length === 0
     ? []
     : [
@@ -544,7 +581,7 @@ const assistantMessageItems = (acc: Accumulator): ReadonlyArray<Item> =>
         },
       ]
 
-const functionCallItems = (acc: Accumulator): ReadonlyArray<Item> =>
+const functionCallItems = (acc: Accumulator): ReadonlyArray<HistoryItem> =>
   pipe(
     acc.functionCalls,
     Arr.map((c) => ({

package/src/index.ts

@@ -1,7 +1,6 @@
 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"

package/src/models.ts

@@ -44,23 +44,6 @@ export type GeminiTtsModel =
   // eslint-disable-next-line @typescript-eslint/ban-types
   | (string & {})
 
-/**
- * Known Gemini models that accept audio input via `inlineData` /
- * `fileData` on `generateContent`. Used by `GeminiTranscriber` —
- * transcription is prompt-driven on top of these models, not a
- * dedicated endpoint.
- *
- * Reference: https://ai.google.dev/gemini-api/docs/audio
- */
-export type GeminiSttModel =
-  | "gemini-3-flash-preview"
-  | "gemini-3.1-pro-preview"
-  | "gemini-3.1-flash-lite-preview"
-  | "gemini-2.5-flash"
-  | "gemini-2.5-pro"
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  | (string & {})
-
 /**
  * 30 prebuilt voice names for Gemini TTS. No custom-voice / cloning path
  * is exposed on this surface, so the tail is stock-only (no