@effect-uai/mistral 0.8.0

package/src/Mistral.ts

@@ -0,0 +1,189 @@
+import { Context, Effect, Layer, Option, Redacted, Result, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import {
+  type CommonRequest,
+  LanguageModel,
+  type LanguageModelService,
+  turnFromStream,
+} from "@effect-uai/core/LanguageModel"
+import * as SSE from "@effect-uai/core/SSE"
+import { descriptorsOf } from "@effect-uai/core/Tool"
+import { type Turn, TurnEvent } from "@effect-uai/core/Turn"
+import {
+  type Accumulator,
+  type WireChunk,
+  accumulatorToTurn,
+  applyChunk,
+  decodeChunk,
+  emptyAccumulator,
+  itemsToMessages,
+  responseFormatWire,
+  toolChoiceWire,
+  toolsWire,
+} from "./codec.js"
+import { httpStatusError } from "./http.js"
+import type { MistralModel } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type MistralRequest = Omit<CommonRequest, "model"> & {
+  /**
+   * Narrows `CommonRequest.model` (`string`) to the typed `MistralModel`
+   * literal union for autocomplete.
+   */
+  readonly model: MistralModel
+  /**
+   * Prepend a safety system prompt (`safe_prompt` on the wire). Off by default.
+   */
+  readonly safePrompt?: boolean
+  /** Deterministic sampling seed (`random_seed` on the wire). */
+  readonly randomSeed?: number
+}
+
+export type MistralService = {
+  /** Stream canonical `TurnEvent`s for one turn. */
+  readonly streamTurn: (request: MistralRequest) => Stream.Stream<TurnEvent, AiError.AiError>
+  /** Drain a single turn and return the assembled `Turn`. */
+  readonly turn: (request: MistralRequest) => Effect.Effect<Turn, AiError.AiError>
+}
+
+/**
+ * Provider-typed service tag. Yield this when you want Mistral-specific options
+ * (`safePrompt`, `randomSeed`); yield the generic `LanguageModel` tag for
+ * provider-portable code. Both are registered by `layer`.
+ */
+export class Mistral extends Context.Service<Mistral, MistralService>()(
+  "@betalyra/effect-uai/providers/mistral/Mistral",
+) {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+}
+
+// ---------------------------------------------------------------------------
+// Request body
+// ---------------------------------------------------------------------------
+
+const buildRequestBody = (request: MistralRequest): Record<string, unknown> => {
+  const tools = toolsWire(descriptorsOf(request.tools))
+  return {
+    model: request.model,
+    stream: true,
+    messages: itemsToMessages(request.history),
+    ...(request.temperature !== undefined && { temperature: request.temperature }),
+    ...(request.topP !== undefined && { top_p: request.topP }),
+    ...(request.maxOutputTokens !== undefined && { max_tokens: request.maxOutputTokens }),
+    ...(request.safePrompt !== undefined && { safe_prompt: request.safePrompt }),
+    ...(request.randomSeed !== undefined && { random_seed: request.randomSeed }),
+    ...(Option.isSome(tools) && { tools: tools.value }),
+    ...(request.toolChoice !== undefined && { tool_choice: toolChoiceWire(request.toolChoice) }),
+    ...(request.structured !== undefined && {
+      response_format: responseFormatWire(request.structured),
+    }),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SSE → WireChunk
+// ---------------------------------------------------------------------------
+
+const parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
+
+/**
+ * Decode one SSE event's `data` payload into a `WireChunk`. Returns `None`
+ * for the `[DONE]` sentinel and for any payload that isn't a chunk we model,
+ * so a stray keep-alive never aborts the turn.
+ */
+const decodeEvent = (data: string): Effect.Effect<Option.Option<WireChunk>> =>
+  data.trim() === "[DONE]"
+    ? Effect.succeedNone
+    : parseJsonUnknown(data).pipe(Effect.flatMap(decodeChunk), Effect.option)
+
+// ---------------------------------------------------------------------------
+// Stream
+// ---------------------------------------------------------------------------
+
+const buildStream = (cfg: Config) => {
+  const baseUrl = cfg.baseUrl ?? "https://api.mistral.ai"
+  const url = `${baseUrl}/v1/chat/completions`
+  return (
+    request: MistralRequest,
+  ): Stream.Stream<TurnEvent, AiError.AiError, HttpClient.HttpClient> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient
+        const httpRequest = HttpClientRequest.post(url).pipe(
+          HttpClientRequest.setHeader("authorization", `Bearer ${Redacted.value(cfg.apiKey)}`),
+          HttpClientRequest.bodyJsonUnsafe(buildRequestBody(request)),
+          HttpClientRequest.accept("text/event-stream"),
+        )
+        const response = yield* client
+          .execute(httpRequest)
+          .pipe(
+            Effect.mapError(
+              (cause): AiError.AiError =>
+                new AiError.Unavailable({ provider: "mistral", raw: cause }),
+            ),
+          )
+        if (response.status >= 400) {
+          const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+          return Stream.fail(httpStatusError(response.status, text))
+        }
+
+        return response.stream.pipe(
+          Stream.mapError(
+            (cause): AiError.AiError =>
+              new AiError.Unavailable({ provider: "mistral", raw: cause }),
+          ),
+          SSE.fromBytes,
+          Stream.mapEffect((ev) => decodeEvent(ev.data)),
+          Stream.filterMap((chunk) =>
+            Option.isSome(chunk) ? Result.succeed(chunk.value) : Result.failVoid,
+          ),
+          Stream.mapAccum((): Accumulator => emptyAccumulator, applyChunk, {
+            onHalt: (acc) => [TurnEvent.TurnComplete({ turn: accumulatorToTurn(acc) })],
+          }),
+        )
+      }),
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/** Build a `MistralService` value. For Layer-based setup, prefer `layer`. */
+export const make = (cfg: Config): Effect.Effect<MistralService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => {
+    const streamTurn: MistralService["streamTurn"] = (request) =>
+      buildStream(cfg)(request).pipe(Stream.provideService(HttpClient.HttpClient, client))
+    return {
+      streamTurn,
+      turn: turnFromStream(streamTurn),
+    }
+  })
+
+/**
+ * Layer that registers both the provider-specific `Mistral` tag and the
+ * generic `LanguageModel` tag, sharing one underlying implementation.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<Mistral | LanguageModel, never, HttpClient.HttpClient> => {
+  const typed = Layer.effect(Mistral, make(cfg))
+  const generic = Layer.effect(
+    LanguageModel,
+    Effect.map(
+      make(cfg),
+      (s): LanguageModelService => ({
+        streamTurn: (request) => s.streamTurn(request as MistralRequest),
+        turn: (request) => s.turn(request as MistralRequest),
+      }),
+    ),
+  )
+  return Layer.merge(typed, generic)
+}

package/src/MistralRealtimeTranscriber.ts

@@ -0,0 +1,60 @@
+/**
+ * Realtime variant of `MistralTranscriber`. Wires `streamTranscriptionFrom`
+ * to the Voxtral Realtime WebSocket endpoint and registers the `SttStreaming`
+ * capability marker, so live-transcription calls compile against this Layer
+ * alone (unlike the sync-only `MistralTranscriber` Layer).
+ *
+ * Pulls in `ws` (optional peer dep) transitively via `./realtimeStt.js`.
+ * Node/Bun only — the browser `WebSocket` API can't set the `Authorization`
+ * header the WS upgrade requires.
+ */
+import { Effect, Layer } from "effect"
+import { HttpClient } from "effect/unstable/http"
+import {
+  type CommonTranscribeRequest,
+  SttStreaming,
+  Transcriber,
+  type TranscriberService,
+} from "@effect-uai/core/Transcriber"
+import {
+  MistralTranscriber,
+  type MistralTranscriberService,
+  type MistralTranscribeRequest,
+  transcribeImpl,
+} from "./MistralTranscriber.js"
+import { type Config, streamTranscription } from "./realtimeStt.js"
+
+export type { Config } from "./realtimeStt.js"
+export {
+  MistralTranscriber,
+  type MistralTranscriberService,
+  type MistralTranscribeRequest,
+} from "./MistralTranscriber.js"
+
+export const make = (
+  cfg: Config,
+): Effect.Effect<MistralTranscriberService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    transcribe: (request) =>
+      transcribeImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+    streamTranscriptionFrom: streamTranscription(cfg),
+  }))
+
+export const layer = (
+  cfg: Config,
+): Layer.Layer<MistralTranscriber | Transcriber | SttStreaming, never, HttpClient.HttpClient> =>
+  Layer.mergeAll(
+    Layer.effect(MistralTranscriber, make(cfg)),
+    Layer.effect(
+      Transcriber,
+      Effect.map(
+        make(cfg),
+        (s): TranscriberService => ({
+          transcribe: (req: CommonTranscribeRequest) =>
+            s.transcribe(req as MistralTranscribeRequest),
+          streamTranscriptionFrom: s.streamTranscriptionFrom,
+        }),
+      ),
+    ),
+    Layer.succeed(SttStreaming, undefined),
+  )

package/src/MistralSynthesizer.ts

@@ -0,0 +1,285 @@
+import {
+  Array as Arr,
+  Context,
+  Effect,
+  Encoding,
+  Layer,
+  Redacted,
+  Result,
+  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 * as Capabilities from "@effect-uai/core/Capabilities"
+import {
+  type CommonStreamSynthesizeRequest,
+  type CommonSynthesizeRequest,
+  SpeechSynthesizer,
+  type SpeechSynthesizerService,
+  TtsIncrementalText,
+} from "@effect-uai/core/SpeechSynthesizer"
+import { containerToTtsFormat, type MistralTtsFormat, realizedTtsFormat } from "./audioCodec.js"
+import { httpStatusError, transportFailure } from "./http.js"
+import type { MistralTtsModel } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Mistral-typed synthesize request. `model` narrows to `MistralTtsModel`;
+ * `voiceId` selects a saved Voxtral voice. `refAudio` (base64 of a 2-3s clip)
+ * triggers zero-shot voice cloning and takes precedence over `voiceId`.
+ */
+export type MistralSynthesizeRequest = Omit<CommonSynthesizeRequest, "model"> & {
+  readonly model: MistralTtsModel
+  readonly refAudio?: string
+}
+
+export type MistralSynthesizerService = {
+  readonly synthesize: (
+    request: MistralSynthesizeRequest,
+  ) => Effect.Effect<AudioBlob, AiError.AiError>
+  readonly streamSynthesis: (
+    request: MistralSynthesizeRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
+  readonly streamSynthesisFrom: <E, R>(
+    textIn: Stream.Stream<string, E, R>,
+    request: CommonStreamSynthesizeRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R>
+  readonly synthesizeDialogue: SpeechSynthesizerService["synthesizeDialogue"]
+  readonly streamSynthesizeDialogue: SpeechSynthesizerService["streamSynthesizeDialogue"]
+}
+
+export class MistralSynthesizer extends Context.Service<
+  MistralSynthesizer,
+  MistralSynthesizerService
+>()("@betalyra/effect-uai/providers/mistral/MistralSynthesizer") {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+}
+
+// ---------------------------------------------------------------------------
+// Codec — request → JSON body
+// ---------------------------------------------------------------------------
+
+const defaultFormat: AudioFormat = { container: "mp3", encoding: "mp3", sampleRate: 24000 }
+
+type WireBody = {
+  readonly model: string
+  readonly input: string
+  readonly response_format: MistralTtsFormat
+  readonly voice_id?: string
+  readonly ref_audio?: string
+}
+
+const buildBody = (
+  request: MistralSynthesizeRequest,
+): Effect.Effect<{ readonly body: WireBody; readonly format: AudioFormat }, AiError.AiError> =>
+  Effect.gen(function* () {
+    // Voxtral has no phoneme field; pronunciations are load-bearing, so reject
+    // rather than silently mispronounce.
+    if (request.pronunciations !== undefined && request.pronunciations.length > 0) {
+      return yield* Effect.fail(
+        new AiError.Unsupported({
+          provider: "mistral",
+          capability: "pronunciations",
+          reason:
+            "Voxtral TTS has no phoneme field. Use a provider with a phoneme path (Inworld, Google) for pronunciation overrides.",
+        }),
+      )
+    }
+    yield* Capabilities.warnDroppedWhen(request.speed, {
+      provider: "mistral",
+      capability: "speed",
+      field: "speed",
+      reason: "Voxtral TTS has no speed control; prosody follows the voice prompt.",
+    })
+    yield* Capabilities.warnDroppedWhen(request.languageCode, {
+      provider: "mistral",
+      capability: "languageCode",
+      field: "languageCode",
+      reason: "Voxtral TTS auto-detects language and clones cross-lingually.",
+    })
+    const responseFormat = yield* containerToTtsFormat(
+      (request.outputFormat ?? defaultFormat).container,
+    )
+    return {
+      body: {
+        model: request.model,
+        input: request.text,
+        response_format: responseFormat,
+        // Cloning clip wins over a saved voice id when both are present.
+        ...(request.refAudio !== undefined
+          ? { ref_audio: request.refAudio }
+          : { voice_id: request.voiceId }),
+      },
+      format: realizedTtsFormat(responseFormat),
+    }
+  })
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing
+// ---------------------------------------------------------------------------
+
+const buildHttpRequest = (cfg: Config, body: WireBody, accept: string) =>
+  HttpClientRequest.post(`${cfg.baseUrl ?? "https://api.mistral.ai"}/v1/audio/speech`).pipe(
+    HttpClientRequest.bearerToken(cfg.apiKey),
+    HttpClientRequest.accept(accept),
+    HttpClientRequest.bodyJsonUnsafe(body),
+  )
+
+// One-shot response: base64 audio. Voxtral's streaming SSE wraps this same
+// payload; since `streamSynthesisFrom` buffers the whole utterance anyway, we
+// drive everything off the simpler one-shot endpoint and slice for pacing.
+const WireResponse = Schema.Struct({ audio_data: Schema.String })
+const decodeResponse = Schema.decodeUnknownEffect(WireResponse)
+
+const decodeAudioData = (b64: string): Effect.Effect<Uint8Array, AiError.AiError> =>
+  Result.match(Encoding.decodeBase64(b64), {
+    onSuccess: Effect.succeed,
+    onFailure: (cause) =>
+      Effect.fail(
+        new AiError.InvalidRequest({ provider: "mistral", param: "audio_data", raw: cause }),
+      ),
+  })
+
+const synthesizeImpl =
+  (cfg: Config) =>
+  (
+    request: MistralSynthesizeRequest,
+  ): Effect.Effect<AudioBlob, AiError.AiError, HttpClient.HttpClient> =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const { body, format } = yield* buildBody(request)
+      const response = yield* client
+        .execute(buildHttpRequest(cfg, body, "application/json"))
+        .pipe(Effect.mapError(transportFailure))
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        yield* Effect.logWarning("[voxtral-tts] request failed", {
+          status: response.status,
+          body: text,
+        })
+        return yield* Effect.fail(httpStatusError(response.status, text))
+      }
+      const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+      const decoded = yield* decodeResponse(json).pipe(Effect.mapError(transportFailure))
+      const bytes = yield* decodeAudioData(decoded.audio_data)
+      yield* Effect.logDebug("[voxtral-tts] ok", {
+        bytes: bytes.byteLength,
+        voice: request.voiceId,
+      })
+      return { format, bytes }
+    })
+
+// ~40 ms frames so the voice loop can pace playback and cut on interrupt.
+const FRAME_BYTES = 8192
+
+const sliceIntoChunks = (bytes: Uint8Array): ReadonlyArray<AudioChunk> =>
+  Arr.makeBy(Math.max(1, Math.ceil(bytes.byteLength / FRAME_BYTES)), (i) => ({
+    bytes: bytes.subarray(i * FRAME_BYTES, (i + 1) * FRAME_BYTES),
+  }))
+
+const streamSynthesisImpl =
+  (cfg: Config) =>
+  (
+    request: MistralSynthesizeRequest,
+  ): Stream.Stream<AudioChunk, AiError.AiError, HttpClient.HttpClient> =>
+    Stream.unwrap(
+      Effect.map(synthesizeImpl(cfg)(request), (blob) =>
+        Stream.fromIterable(sliceIntoChunks(blob.bytes)),
+      ),
+    )
+
+// ---------------------------------------------------------------------------
+// Dialogue — unsupported (Voxtral has no multi-speaker endpoint)
+// ---------------------------------------------------------------------------
+
+const synthesizeDialogueUnsupported: SpeechSynthesizerService["synthesizeDialogue"] = () =>
+  Effect.fail(
+    new AiError.Unsupported({
+      provider: "mistral",
+      capability: "synthesizeDialogue",
+      reason: "Voxtral TTS has no multi-speaker dialogue endpoint.",
+    }),
+  )
+
+const streamSynthesizeDialogueUnsupported: SpeechSynthesizerService["streamSynthesizeDialogue"] =
+  () =>
+    Stream.fail(
+      new AiError.Unsupported({
+        provider: "mistral",
+        capability: "streamSynthesizeDialogue",
+        reason: "Voxtral TTS has no multi-speaker dialogue endpoint.",
+      }),
+    )
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export const make = (
+  cfg: Config,
+): Effect.Effect<MistralSynthesizerService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    synthesize: (request) =>
+      synthesizeImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+    streamSynthesis: (request) =>
+      streamSynthesisImpl(cfg)(request).pipe(Stream.provideService(HttpClient.HttpClient, client)),
+    // Voxtral has no incremental-text-in WS endpoint, so we fold the text
+    // stream into one utterance and hand it to the chunked streaming endpoint.
+    // Audio still streams out; only the text side buffers (one turn per call).
+    streamSynthesisFrom: (textIn, request) =>
+      Stream.unwrap(
+        Effect.map(
+          Stream.runFold(
+            textIn,
+            () => "",
+            (acc, s) => acc + s,
+          ),
+          (text) =>
+            streamSynthesisImpl(cfg)({ ...request, text } as MistralSynthesizeRequest).pipe(
+              Stream.provideService(HttpClient.HttpClient, client),
+            ),
+        ),
+      ),
+    synthesizeDialogue: synthesizeDialogueUnsupported,
+    streamSynthesizeDialogue: streamSynthesizeDialogueUnsupported,
+  }))
+
+/**
+ * Layer registering `MistralSynthesizer`, the generic `SpeechSynthesizer` tag,
+ * and the `TtsIncrementalText` capability marker (so `streamSynthesisFrom`
+ * composes — note the text side buffers; see its docs).
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<
+  MistralSynthesizer | SpeechSynthesizer | TtsIncrementalText,
+  never,
+  HttpClient.HttpClient
+> =>
+  Layer.mergeAll(
+    Layer.effect(MistralSynthesizer, make(cfg)),
+    Layer.effect(
+      SpeechSynthesizer,
+      Effect.map(
+        make(cfg),
+        (s): SpeechSynthesizerService => ({
+          synthesize: (req: CommonSynthesizeRequest) =>
+            s.synthesize(req as MistralSynthesizeRequest),
+          streamSynthesis: (req: CommonSynthesizeRequest) =>
+            s.streamSynthesis(req as MistralSynthesizeRequest),
+          streamSynthesisFrom: s.streamSynthesisFrom,
+          synthesizeDialogue: s.synthesizeDialogue,
+          streamSynthesizeDialogue: s.streamSynthesizeDialogue,
+        }),
+      ),
+    ),
+    Layer.succeed(TtsIncrementalText, undefined),
+  )