@effect-uai/google 0.2.0 → 0.4.0

package/src/GeminiEmbedding.ts

@@ -0,0 +1,351 @@
+import { Context, Effect, Encoding, Layer, Match, Redacted, Schema } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import type { Embedding, EmbedContentPart, EmbedInput, Usage } from "@effect-uai/core/Embedding"
+import {
+  type CommonEmbedManyRequest,
+  type CommonEmbedRequest,
+  EmbeddingModel,
+  type EmbeddingModelService,
+  type EmbedManyResponse,
+  type EmbedResponse,
+} from "@effect-uai/core/EmbeddingModel"
+import type { ImageSource } from "@effect-uai/core/Image"
+import type { GoogleEmbeddingModel } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Gemini's task-type enum, exposed under our friendly names. Mapped to the
+ * wire `taskType` values inside the codec. Honoured by
+ * `gemini-embedding-001`; ignored by `gemini-embedding-2` (which expects
+ * task instructions in the prompt text instead).
+ */
+export type GoogleEmbeddingTask =
+  | "query"
+  | "document"
+  | "similarity"
+  | "classification"
+  | "clustering"
+  | "qa"
+  | "fact_verification"
+  | "code_query"
+
+export type GeminiEmbedRequest = Omit<CommonEmbedRequest, "model" | "task" | "encoding"> & {
+  /** Narrows `CommonEmbedRequest.model` to the typed Google union. */
+  readonly model: GoogleEmbeddingModel
+  /**
+   * Widens the cross-provider `"query" | "document"` to the full Google
+   * task enum. Optional. Honoured by `gemini-embedding-001`; ignored by
+   * `gemini-embedding-2`.
+   */
+  readonly task?: GoogleEmbeddingTask
+  /**
+   * Optional document title. Only meaningful for `RETRIEVAL_DOCUMENT`
+   * tasks on `gemini-embedding-001`.
+   */
+  readonly title?: string
+}
+
+export type GeminiEmbedManyRequest = Omit<GeminiEmbedRequest, "input"> & {
+  readonly inputs: ReadonlyArray<EmbedInput>
+}
+
+export type GeminiEmbeddingService = {
+  readonly embed: (request: GeminiEmbedRequest) => Effect.Effect<EmbedResponse, AiError.AiError>
+  readonly embedMany: (
+    request: GeminiEmbedManyRequest,
+  ) => Effect.Effect<EmbedManyResponse, AiError.AiError>
+}
+
+/**
+ * Provider-typed service tag. Yield this when you want Gemini-specific
+ * options (full `task` enum, `title`); yield the generic `EmbeddingModel`
+ * tag for provider-portable code. Both are registered by `layer`.
+ */
+export class GeminiEmbedding extends Context.Service<GeminiEmbedding, GeminiEmbeddingService>()(
+  "@betalyra/effect-uai/providers/google/GeminiEmbedding",
+) {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+}
+
+// ---------------------------------------------------------------------------
+// Codec - request body
+// ---------------------------------------------------------------------------
+
+const taskToWire: Record<GoogleEmbeddingTask, string> = {
+  query: "RETRIEVAL_QUERY",
+  document: "RETRIEVAL_DOCUMENT",
+  similarity: "SEMANTIC_SIMILARITY",
+  classification: "CLASSIFICATION",
+  clustering: "CLUSTERING",
+  qa: "QUESTION_ANSWERING",
+  fact_verification: "FACT_VERIFICATION",
+  code_query: "CODE_RETRIEVAL_QUERY",
+}
+
+type WireTextPart = {
+  readonly text: string
+}
+type WireInlineDataPart = {
+  readonly inlineData: { readonly mimeType: string; readonly data: string }
+}
+type WirePart = WireTextPart | WireInlineDataPart
+type WireContent = {
+  readonly parts: ReadonlyArray<WirePart>
+}
+
+const urlRejected = (param: string): AiError.AiError =>
+  new AiError.InvalidRequest({
+    provider: "gemini",
+    param,
+    raw: "URL-form image inputs aren't supported; pass base64 or bytes",
+  })
+
+/**
+ * Pre-uploading via Google's Files API isn't free, so we reject `url`
+ * sources up front rather than silently dropping them. Users with HTTPS
+ * URLs should fetch + pass `bytes` (or `base64`).
+ */
+const imageSourceToPart = (param: string) =>
+  Match.type<ImageSource>().pipe(
+    Match.tag(
+      "base64",
+      (s): Effect.Effect<WirePart, AiError.AiError> =>
+        Effect.succeed({ inlineData: { mimeType: s.mimeType, data: s.base64 } }),
+    ),
+    Match.tag(
+      "bytes",
+      (s): Effect.Effect<WirePart, AiError.AiError> =>
+        Effect.succeed({
+          inlineData: { mimeType: s.mimeType, data: Encoding.encodeBase64(s.bytes) },
+        }),
+    ),
+    Match.tag(
+      "url",
+      (): Effect.Effect<WirePart, AiError.AiError> => Effect.fail(urlRejected(param)),
+    ),
+    Match.exhaustive,
+  )
+
+const contentPartToPart = (
+  param: string,
+  part: EmbedContentPart,
+): Effect.Effect<WirePart, AiError.AiError> =>
+  "text" in part ? Effect.succeed({ text: part.text }) : imageSourceToPart(param)(part.image)
+
+const inputToContent = (input: EmbedInput): Effect.Effect<WireContent, AiError.AiError> => {
+  if (typeof input === "string") return Effect.succeed({ parts: [{ text: input }] })
+  if ("text" in input) return Effect.succeed({ parts: [{ text: input.text }] })
+  if ("image" in input) {
+    return imageSourceToPart("input.image")(input.image).pipe(
+      Effect.map((part) => ({ parts: [part] })),
+    )
+  }
+  return Effect.forEach(input.content, (p) => contentPartToPart("input.content[].image", p)).pipe(
+    Effect.map((parts) => ({ parts })),
+  )
+}
+
+type WireSingleBody = {
+  readonly content: WireContent
+  readonly taskType?: string
+  readonly outputDimensionality?: number
+  readonly title?: string
+}
+
+const wireOptions = (
+  request: Pick<GeminiEmbedRequest, "task" | "dimensions" | "title">,
+): Omit<WireSingleBody, "content"> => ({
+  ...(request.task !== undefined && { taskType: taskToWire[request.task] }),
+  ...(request.dimensions !== undefined && { outputDimensionality: request.dimensions }),
+  ...(request.title !== undefined && { title: request.title }),
+})
+
+const buildSingleBody = (
+  request: GeminiEmbedRequest,
+): Effect.Effect<WireSingleBody, AiError.AiError> =>
+  inputToContent(request.input).pipe(
+    Effect.map((content) => ({ content, ...wireOptions(request) })),
+  )
+
+type WireBatchEntry = WireSingleBody & {
+  readonly model: string
+}
+type WireBatchBody = {
+  readonly requests: ReadonlyArray<WireBatchEntry>
+}
+
+const buildBatchBody = (
+  request: GeminiEmbedManyRequest,
+): Effect.Effect<WireBatchBody, AiError.AiError> => {
+  const modelPath = `models/${request.model}`
+  const options = wireOptions(request)
+  return Effect.forEach(request.inputs, (input) =>
+    inputToContent(input).pipe(
+      Effect.map((content): WireBatchEntry => ({ model: modelPath, content, ...options })),
+    ),
+  ).pipe(Effect.map((requests) => ({ requests })))
+}
+
+// ---------------------------------------------------------------------------
+// Codec - response
+// ---------------------------------------------------------------------------
+
+const WireEmbedding = Schema.Struct({
+  values: Schema.Array(Schema.Number),
+})
+
+const WireSingleResponse = Schema.Struct({
+  embedding: WireEmbedding,
+})
+
+const WireBatchResponse = Schema.Struct({
+  embeddings: Schema.Array(WireEmbedding),
+})
+
+const valuesToEmbedding = (values: ReadonlyArray<number>): Embedding => ({
+  _tag: "float32",
+  vector: Float32Array.from(values),
+})
+
+// Gemini's embed endpoints don't return token-count metadata. Estimating
+// client-side would be provider-specific cruft; honest `undefined` is better.
+const emptyUsage: Usage = {}
+
+// ---------------------------------------------------------------------------
+// HTTP errors
+// ---------------------------------------------------------------------------
+
+const httpStatusError = (status: number, body: string): AiError.AiError => {
+  const provider = "gemini"
+  const raw = body
+  if (status === 429) return new AiError.RateLimited({ provider, raw })
+  if (status === 408 || status === 504) return new AiError.Timeout({ provider, raw })
+  if (status === 401) return new AiError.AuthFailed({ provider, subtype: "auth", raw })
+  if (status === 403) return new AiError.AuthFailed({ provider, subtype: "permission", raw })
+  if (status === 402) return new AiError.AuthFailed({ provider, subtype: "billing", raw })
+  if (status === 413) return new AiError.ContextLengthExceeded({ provider, raw })
+  if (status >= 500) return new AiError.Unavailable({ provider, status, raw })
+  return new AiError.InvalidRequest({ provider, raw })
+}
+
+const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "gemini", raw: cause })
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing - send a JSON body, error-map status, return parsed JSON.
+// ---------------------------------------------------------------------------
+
+const postJson = (
+  cfg: Config,
+  url: string,
+  body: unknown,
+): Effect.Effect<unknown, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.post(url).pipe(
+      HttpClientRequest.setHeader("x-goog-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(body),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* Effect.fail(httpStatusError(response.status, text))
+    }
+    return yield* response.json.pipe(Effect.mapError(transportFailure))
+  })
+
+const decodeSingle = (json: unknown) =>
+  Schema.decodeUnknownEffect(WireSingleResponse)(json).pipe(Effect.mapError(transportFailure))
+
+const decodeBatch = (json: unknown) =>
+  Schema.decodeUnknownEffect(WireBatchResponse)(json).pipe(Effect.mapError(transportFailure))
+
+const baseUrl = (cfg: Config): string =>
+  cfg.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta"
+
+// ---------------------------------------------------------------------------
+// Service implementation
+// ---------------------------------------------------------------------------
+
+const embedImpl =
+  (cfg: Config) =>
+  (
+    request: GeminiEmbedRequest,
+  ): Effect.Effect<EmbedResponse, AiError.AiError, HttpClient.HttpClient> =>
+    buildSingleBody(request).pipe(
+      Effect.flatMap((body) =>
+        postJson(cfg, `${baseUrl(cfg)}/models/${request.model}:embedContent`, body),
+      ),
+      Effect.flatMap(decodeSingle),
+      Effect.map(
+        (decoded): EmbedResponse => ({
+          embedding: valuesToEmbedding(decoded.embedding.values),
+          usage: emptyUsage,
+        }),
+      ),
+    )
+
+const embedManyImpl =
+  (cfg: Config) =>
+  (
+    request: GeminiEmbedManyRequest,
+  ): Effect.Effect<EmbedManyResponse, AiError.AiError, HttpClient.HttpClient> =>
+    buildBatchBody(request).pipe(
+      Effect.flatMap((body) =>
+        postJson(cfg, `${baseUrl(cfg)}/models/${request.model}:batchEmbedContents`, body),
+      ),
+      Effect.flatMap(decodeBatch),
+      Effect.map(
+        (decoded): EmbedManyResponse => ({
+          embeddings: decoded.embeddings.map((e) => valuesToEmbedding(e.values)),
+          usage: emptyUsage,
+        }),
+      ),
+    )
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `GeminiEmbeddingService` value. For Layer-based setup, prefer
+ * `layer`.
+ */
+export const make = (
+  cfg: Config,
+): Effect.Effect<GeminiEmbeddingService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    embed: (request) =>
+      embedImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+    embedMany: (request) =>
+      embedManyImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+  }))
+
+/**
+ * Layer that registers both the provider-specific `GeminiEmbedding` tag
+ * and the generic `EmbeddingModel` tag, sharing one underlying
+ * implementation.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<GeminiEmbedding | EmbeddingModel, never, HttpClient.HttpClient> => {
+  const typed = Layer.effect(GeminiEmbedding, make(cfg))
+  const generic = Layer.effect(
+    EmbeddingModel,
+    Effect.map(
+      make(cfg),
+      (s): EmbeddingModelService => ({
+        embed: (req: CommonEmbedRequest) => s.embed(req as GeminiEmbedRequest),
+        embedMany: (req: CommonEmbedManyRequest) => s.embedMany(req as GeminiEmbedManyRequest),
+      }),
+    ),
+  )
+  return Layer.merge(typed, generic)
+}

package/src/GeminiSynthesizer.test.ts

@@ -0,0 +1,93 @@
+import { 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 type { AudioBlob } from "@effect-uai/core/Audio"
+import * as SpeechSynthesizer from "@effect-uai/core/SpeechSynthesizer"
+import * as GeminiSynthesizer from "./GeminiSynthesizer.js"
+
+const cfg: GeminiSynthesizer.Config = { apiKey: Redacted.make("test-key") }
+// FetchHttpClient is required for `make`, but these tests only exercise
+// the codec and the compile-time / runtime Unsupported branches — no
+// real HTTP call is made.
+const live = Layer.provide(GeminiSynthesizer.layer(cfg), FetchHttpClient.layer)
+
+describe("GeminiSynthesizer.realizeOutput", () => {
+  it("maps raw to native PCM 24 kHz mono with an identity wrapper", async () => {
+    const [format, wrap] = await Effect.runPromise(GeminiSynthesizer.realizeOutput("raw"))
+    expect(format).toEqual({
+      container: "raw",
+      encoding: "pcm_s16le",
+      sampleRate: 24000,
+      channels: 1,
+    })
+    const pcm = new Uint8Array([1, 2, 3, 4])
+    expect(wrap(pcm)).toBe(pcm)
+  })
+
+  it("maps wav to a RIFF/WAVE wrapper that prepends a 44-byte header", async () => {
+    const [format, wrap] = await Effect.runPromise(GeminiSynthesizer.realizeOutput("wav"))
+    expect(format.container).toBe("wav")
+    const out = wrap(new Uint8Array([0, 1, 2, 3]))
+    expect(out.length).toBe(44 + 4)
+    const ascii = (start: number, len: number) =>
+      String.fromCharCode(...Array.from(out.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")
+  })
+
+  it("fails Unsupported for mp3 / opus / aac / flac / ogg / webm", async () => {
+    const exit = await Effect.runPromiseExit(GeminiSynthesizer.realizeOutput("mp3"))
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") {
+      expect(JSON.stringify(exit.cause)).toContain("Unsupported")
+      expect(JSON.stringify(exit.cause)).toContain("outputFormat")
+    }
+  })
+})
+
+describe("GeminiSynthesizer capability guards (runtime)", () => {
+  it("streamSynthesisFrom returns an Unsupported stream", async () => {
+    const program = GeminiSynthesizer.GeminiSynthesizer.use((s) =>
+      Stream.runDrain(
+        s.streamSynthesisFrom(Stream.fromIterable(["hi"]), {
+          model: "gemini-2.5-flash-preview-tts",
+          voiceId: "Kore",
+        }),
+      ),
+    )
+    const exit = await Effect.runPromiseExit(program.pipe(Effect.provide(live)))
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") {
+      expect(JSON.stringify(exit.cause)).toContain("Unsupported")
+      expect(JSON.stringify(exit.cause)).toContain("streamSynthesisFrom")
+    }
+  })
+})
+
+describe("GeminiSynthesizer Layer (compile-time)", () => {
+  it("leaves `TtsIncrementalText` unsatisfied when using `streamSynthesisFrom` against this Layer", () => {
+    const tokens: Stream.Stream<string> = Stream.fromIterable(["a"])
+    const audio = tokens.pipe(
+      SpeechSynthesizer.streamSynthesisFrom({
+        model: "gemini-2.5-flash-preview-tts",
+        voiceId: "Kore",
+      }),
+    )
+    const provided = Stream.runDrain(audio).pipe(Effect.provide(live))
+    expectTypeOf(provided).toEqualTypeOf<
+      Effect.Effect<void, AiError.AiError, SpeechSynthesizer.TtsIncrementalText>
+    >()
+  })
+
+  it("sync `synthesize` requires no marker", () => {
+    const synth = SpeechSynthesizer.synthesize({
+      text: "hi",
+      model: "gemini-2.5-flash-preview-tts",
+      voiceId: "Kore",
+    }).pipe(Effect.provide(live))
+    expectTypeOf(synth).toEqualTypeOf<Effect.Effect<AudioBlob, AiError.AiError, never>>()
+  })
+})

package/src/GeminiSynthesizer.ts

@@ -0,0 +1,214 @@
+import { Context, Effect, Layer, Match, Redacted, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioBlob, AudioChunk, AudioFormat } from "@effect-uai/core/Audio"
+import {
+  type CommonStreamSynthesizeRequest,
+  type CommonSynthesizeRequest,
+  SpeechSynthesizer,
+  type SpeechSynthesizerService,
+} from "@effect-uai/core/SpeechSynthesizer"
+import {
+  decodeBase64Audio,
+  httpStatusError,
+  transportFailure,
+  wrapPcmAsWav,
+} from "./geminiSpeechCodec.js"
+import type { GeminiTtsModel, GeminiVoiceName } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type GeminiSynthesizeRequest = Omit<CommonSynthesizeRequest, "model" | "voiceId"> & {
+  readonly model: GeminiTtsModel
+  readonly voiceId: GeminiVoiceName
+}
+
+export type GeminiSynthesizerService = {
+  readonly synthesize: (r: GeminiSynthesizeRequest) => Effect.Effect<AudioBlob, AiError.AiError>
+  readonly streamSynthesis: (
+    r: GeminiSynthesizeRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
+  readonly streamSynthesisFrom: SpeechSynthesizerService["streamSynthesisFrom"]
+}
+
+export class GeminiSynthesizer extends Context.Service<
+  GeminiSynthesizer,
+  GeminiSynthesizerService
+>()("@betalyra/effect-uai/providers/google/GeminiSynthesizer") {}
+
+export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+
+// ---------------------------------------------------------------------------
+// Codec — Gemini TTS always emits 24 kHz mono signed-16 PCM. Caller picks
+// raw bytes or WAV-wrapped.
+// ---------------------------------------------------------------------------
+
+const PCM_RATE = 24000
+const PCM_CHANNELS = 1
+
+export const realizeOutput = Match.type<AudioFormat["container"]>().pipe(
+  Match.when("raw", () =>
+    Effect.succeed([
+      { container: "raw", encoding: "pcm_s16le", sampleRate: PCM_RATE, channels: PCM_CHANNELS },
+      (b: Uint8Array) => b,
+    ] as const),
+  ),
+  Match.when("wav", () =>
+    Effect.succeed([
+      { container: "wav", encoding: "pcm_s16le", sampleRate: PCM_RATE, channels: PCM_CHANNELS },
+      (b: Uint8Array) => wrapPcmAsWav(b, PCM_RATE, PCM_CHANNELS),
+    ] as const),
+  ),
+  Match.whenOr("mp3", "opus", "aac", "flac", "ogg", "webm", (c) =>
+    Effect.fail(
+      new AiError.Unsupported({
+        provider: "gemini",
+        capability: "outputFormat",
+        reason: `Gemini TTS emits raw 16-bit PCM at 24 kHz. Request "raw" or "wav"; ${c} is unavailable.`,
+      }),
+    ),
+  ),
+  Match.exhaustive,
+)
+
+// ---------------------------------------------------------------------------
+// Wire
+// ---------------------------------------------------------------------------
+
+const Wire = Schema.Struct({
+  candidates: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        content: Schema.optional(
+          Schema.Struct({
+            parts: Schema.optional(
+              Schema.Array(
+                Schema.Struct({
+                  inlineData: Schema.optional(
+                    Schema.Struct({
+                      mimeType: Schema.optional(Schema.String),
+                      data: Schema.String,
+                    }),
+                  ),
+                }),
+              ),
+            ),
+          }),
+        ),
+      }),
+    ),
+  ),
+})
+const decodeWire = Schema.decodeUnknownEffect(Wire)
+
+const findInline = (wire: typeof Wire.Type) =>
+  (wire.candidates ?? [])
+    .flatMap((c) => c.content?.parts ?? [])
+    .find((p) => p.inlineData !== undefined)?.inlineData
+
+const ttsBody = (r: GeminiSynthesizeRequest) => ({
+  contents: [{ parts: [{ text: r.text }] }],
+  generationConfig: {
+    responseModalities: ["AUDIO"],
+    speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: r.voiceId } } },
+  },
+})
+
+// ---------------------------------------------------------------------------
+// Service implementation
+// ---------------------------------------------------------------------------
+
+const baseUrl = (cfg: Config) => cfg.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta"
+
+const synthesizeImpl = (cfg: Config) => (request: GeminiSynthesizeRequest) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const [format, wrap] = yield* realizeOutput(request.outputFormat?.container ?? "raw")
+    const httpRequest = HttpClientRequest.post(
+      `${baseUrl(cfg)}/models/${request.model}:generateContent`,
+    ).pipe(
+      HttpClientRequest.setHeader("x-goog-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(ttsBody(request)),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* Effect.fail(httpStatusError(response.status, text))
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    const inline = yield* decodeWire(json).pipe(
+      Effect.map(findInline),
+      Effect.mapError((cause) => new AiError.GenerationFailed({ provider: "gemini", raw: cause })),
+      Effect.flatMap((found) =>
+        found === undefined
+          ? Effect.fail(
+              new AiError.GenerationFailed({
+                provider: "gemini",
+                raw: {
+                  message: "Gemini TTS response had no inlineData audio part.",
+                  hint: "Likely a prompt-safety rejection or the model didn't honour responseModalities.",
+                  response: json,
+                },
+              }),
+            )
+          : Effect.succeed(found),
+      ),
+    )
+    const pcm = yield* decodeBase64Audio(inline.data)
+    return { format, bytes: wrap(pcm) } satisfies AudioBlob
+  })
+
+const unsupportedStreamFrom: SpeechSynthesizerService["streamSynthesisFrom"] = () =>
+  Stream.fail(
+    new AiError.Unsupported({
+      provider: "gemini",
+      capability: "streamSynthesisFrom",
+      reason:
+        "Gemini TTS via generateContent is sync-only. Use Cloud Text-to-Speech (Chirp 3 HD) for incremental text-in.",
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export const make = (cfg: Config) =>
+  Effect.map(
+    HttpClient.HttpClient.asEffect(),
+    (client): GeminiSynthesizerService => ({
+      synthesize: (r) =>
+        synthesizeImpl(cfg)(r).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+      streamSynthesis: (r) =>
+        Stream.fromEffect(synthesizeImpl(cfg)(r)).pipe(
+          Stream.map((b): AudioChunk => ({ bytes: b.bytes })),
+          Stream.provideService(HttpClient.HttpClient, client),
+        ),
+      streamSynthesisFrom: unsupportedStreamFrom,
+    }),
+  )
+
+/**
+ * Layer registers both `GeminiSynthesizer` and the generic
+ * `SpeechSynthesizer`. Does NOT register `TtsIncrementalText` — Gemini
+ * TTS is sync-only at the wire level, so `streamSynthesisFrom` against
+ * this Layer alone is a compile-time error.
+ */
+export const layer = (cfg: Config) =>
+  Layer.merge(
+    Layer.effect(GeminiSynthesizer, make(cfg)),
+    Layer.effect(
+      SpeechSynthesizer,
+      Effect.map(
+        make(cfg),
+        (s): SpeechSynthesizerService => ({
+          synthesize: (req: CommonSynthesizeRequest) =>
+            s.synthesize(req as GeminiSynthesizeRequest),
+          streamSynthesis: (req: CommonSynthesizeRequest) =>
+            s.streamSynthesis(req as GeminiSynthesizeRequest),
+          streamSynthesisFrom: s.streamSynthesisFrom,
+        }),
+      ),
+    ),
+  )