@effect-uai/mistral 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/mistral",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Mistral provider for @effect-uai/core: chat-completions plus Voxtral speech-to-text and text-to-speech.",
   "keywords": [
     "ai",
@@ -59,18 +59,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@effect-uai/chat-completions": "0.17.0"
+    "@effect-uai/chat-completions": "0.18.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.13",
-    "effect": "4.0.0-rc.111",
+    "effect": "4.0.1",
     "typescript": "^7.0.2",
     "ws": "^8.18.0",
-    "@effect-uai/core": "0.17.0"
+    "@effect-uai/core": "0.18.0"
   },
   "peerDependencies": {
     "@effect-uai/core": ">=0.2.0 <1",
-    "effect": ">=4.0.0-rc.111 <5.0.0",
+    "effect": ">=4.0.1 <5.0.0",
     "ws": "^8.0.0"
   },
   "peerDependenciesMeta": {

package/src/Mistral.ts

@@ -1,5 +1,5 @@
 import { Context, Effect, Layer, Option, Redacted, Result, Schema, Stream } from "effect"
-import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import { HttpClient, HttpClientRequest } from "effect/http"
 import * as AiError from "@effect-uai/core/AiError"
 import * as Capabilities from "@effect-uai/core/Capabilities"
 import {

package/src/MistralRealtimeTranscriber.ts

@@ -9,7 +9,7 @@
  * header the WS upgrade requires.
  */
 import { Effect, Layer } from "effect"
-import { HttpClient } from "effect/unstable/http"
+import { HttpClient } from "effect/http"
 import {
   type CommonTranscribeRequest,
   SttStreaming,

package/src/MistralSynthesizer.ts

@@ -1,15 +1,6 @@
-import {
-  Array as Arr,
-  Context,
-  Effect,
-  Encoding,
-  Layer,
-  Redacted,
-  Result,
-  Schema,
-  Stream,
-} from "effect"
-import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import { Array as Arr, Context, Effect, Layer, Redacted, Result, Schema, Stream } from "effect"
+import { Base64 } from "effect/encoding"
+import { HttpClient, HttpClientRequest } from "effect/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"
@@ -140,7 +131,7 @@ 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), {
+  Result.match(Base64.decode(b64), {
     onSuccess: Effect.succeed,
     onFailure: (cause) =>
       Effect.fail(

package/src/MistralTranscriber.ts

@@ -1,5 +1,5 @@
 import { Array as Arr, Context, Effect, Layer, Redacted, Schema, Stream } from "effect"
-import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import { HttpClient, HttpClientRequest } from "effect/http"
 import * as AiError from "@effect-uai/core/AiError"
 import * as Capabilities from "@effect-uai/core/Capabilities"
 import { isAudioUrl } from "@effect-uai/core/Audio"

package/src/audioCodec.ts

@@ -1,4 +1,5 @@
-import { Array as Arr, Effect, Encoding, Match, Option, Result } from "effect"
+import { Array as Arr, Effect, Match, Option, Result } from "effect"
+import { Base64 } from "effect/encoding"
 import * as AiError from "@effect-uai/core/AiError"
 import type { AudioFormat, AudioSource } from "@effect-uai/core/Audio"
 
@@ -7,7 +8,7 @@ import type { AudioFormat, AudioSource } from "@effect-uai/core/Audio"
 // ---------------------------------------------------------------------------
 
 const decodeBase64ToBytes = (b64: string): Effect.Effect<Uint8Array, AiError.AiError> =>
-  Result.match(Encoding.decodeBase64(b64), {
+  Result.match(Base64.decode(b64), {
     onSuccess: Effect.succeed,
     onFailure: (cause) =>
       Effect.fail(new AiError.InvalidRequest({ provider: "mistral", param: "audio", raw: cause })),

package/src/codec.ts

@@ -1,4 +1,5 @@
-import { Array as Arr, Effect, Encoding, Match, Option, Result } from "effect"
+import { Array as Arr, Effect, Match, Option, Result } from "effect"
+import { Base64 } from "effect/encoding"
 import type { ContentBlock, HistoryItem, InputImage } from "@effect-uai/core/Items"
 
 // The streaming decoder, tool encoding, and terminal-turn assembly are the
@@ -37,7 +38,7 @@ type WireMessage = {
 const imageSourceToUrl = Match.type<InputImage["source"]>().pipe(
   Match.tag("url", (s) => s.url),
   Match.tag("base64", (s) => `data:${s.mimeType};base64,${s.base64}`),
-  Match.tag("bytes", (s) => `data:${s.mimeType};base64,${Encoding.encodeBase64(s.bytes)}`),
+  Match.tag("bytes", (s) => `data:${s.mimeType};base64,${Base64.encode(s.bytes)}`),
   Match.exhaustive,
 )
 

package/src/http.ts

@@ -1,5 +1,5 @@
 import { Effect, Match } from "effect"
-import { HttpClientRequest } from "effect/unstable/http"
+import { HttpClientRequest } from "effect/http"
 import * as AiError from "@effect-uai/core/AiError"
 import * as Multipart from "@effect-uai/core/Multipart"
 

package/src/onHalt.test.ts

@@ -1,5 +1,5 @@
 import { Effect, Exit, Redacted, Stream } from "effect"
-import { HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { HttpClient, HttpClientResponse } from "effect/http"
 import { describe, expect, it } from "vitest"
 import { TurnEvent } from "@effect-uai/core/Turn"
 import { make as makeMistral } from "./Mistral.js"

package/src/realtimeStt.test.ts

@@ -0,0 +1,116 @@
+import { describe, it } from "@effect/vitest"
+import { Effect, Exit, Fiber, Redacted, Stream } from "effect"
+import { TestClock } from "effect/testing"
+import { expect } from "vitest"
+import * as FakeWebSocket from "@effect-uai/core/testing/FakeWebSocket"
+import { streamTranscription } from "./realtimeStt.js"
+
+const pcm = { container: "raw", encoding: "pcm_s16le", sampleRate: 16000, channels: 1 } as const
+
+const request = { model: "voxtral-mini-transcribe-realtime-2602", inputFormat: pcm }
+
+const sessionCreated = {
+  type: "session.created",
+  session: { request_id: "req_1", model: request.model },
+}
+
+const delta = (text: string) => ({ type: "transcription.text.delta", text })
+
+const start = <E>(
+  server: FakeWebSocket.FakeWebSocketServer,
+  audioIn: Stream.Stream<Uint8Array, E>,
+) =>
+  streamTranscription({ apiKey: Redacted.make("test-key"), webSocket: server.connect })(
+    audioIn,
+    request,
+  ).pipe(Stream.runCollect, Effect.exit, Effect.forkChild)
+
+/** Run a transcription against `server`, closing it, if asked, once the frames are in. */
+const transcribe = <E>(
+  server: FakeWebSocket.FakeWebSocketServer,
+  audioIn: Stream.Stream<Uint8Array, E>,
+  close?: { readonly code: number; readonly afterSent?: number },
+) =>
+  Effect.gen(function* () {
+    const collector = yield* start(server, audioIn)
+    if (close !== undefined) {
+      yield* server.greeted
+      yield* server.awaitSent(close.afterSent ?? 0)
+      yield* server.close(close.code)
+    }
+    return yield* Fiber.join(collector)
+  })
+
+describe("Mistral Realtime STT socket", () => {
+  it.live("configures the session before any audio, and ends on a clean close", () =>
+    Effect.gen(function* () {
+      const server = yield* FakeWebSocket.make({
+        greeting: [
+          sessionCreated,
+          delta("hel"),
+          delta("lo"),
+          { type: "transcription.done", text: "hello", model: request.model, segments: [] },
+          { type: "error", error: { message: "slow down", code: 3001 } },
+        ],
+      })
+      const exit = yield* transcribe(server, Stream.make(new Uint8Array([1, 2])), {
+        code: 1000,
+        afterSent: 3,
+      })
+
+      expect(exit).toEqual(
+        Exit.succeed([
+          { _tag: "partial", text: "hel" },
+          { _tag: "partial", text: "hello" },
+          { _tag: "final", text: "hello" },
+          { _tag: "error", code: "3001", message: "slow down" },
+        ]),
+      )
+      const sent = (yield* server.sent) as ReadonlyArray<{ type: string }>
+      expect(sent.map((f) => f.type)).toEqual([
+        "session.update",
+        "input_audio.append",
+        "input_audio.end",
+      ])
+    }).pipe(Effect.scoped),
+  )
+
+  it.live("fails rather than ending when the connection drops", () =>
+    Effect.gen(function* () {
+      const server = yield* FakeWebSocket.make({ greeting: [sessionCreated] })
+      const exit = yield* transcribe(server, Stream.never, { code: 1011 })
+
+      expect(Exit.isFailure(exit) && JSON.stringify(exit.cause)).toContain("Unavailable")
+    }).pipe(Effect.scoped),
+  )
+
+  it.live("fails with the audio input's own error", () =>
+    Effect.gen(function* () {
+      const server = yield* FakeWebSocket.make({ greeting: [sessionCreated] })
+      const exit = yield* transcribe(server, Stream.fail("microphone unplugged"))
+
+      expect(Exit.isFailure(exit) && JSON.stringify(exit.cause)).toContain("microphone unplugged")
+    }).pipe(Effect.scoped),
+  )
+
+  it.effect("commits a synthetic final once the deltas go quiet", () =>
+    Effect.gen(function* () {
+      const server = yield* FakeWebSocket.make({
+        greeting: [sessionCreated, delta("hel"), delta("lo ")],
+      })
+      const collector = yield* start(server, Stream.never)
+      yield* server.greeted
+      yield* TestClock.withLive(Effect.sleep("5 millis"))
+      yield* TestClock.adjust("1 second")
+      yield* server.close(1000)
+
+      expect(yield* Fiber.join(collector)).toEqual(
+        Exit.succeed([
+          { _tag: "partial", text: "hel" },
+          { _tag: "partial", text: "hello " },
+          { _tag: "final", text: "hello" },
+        ]),
+      )
+    }).pipe(Effect.scoped),
+  )
+})

package/src/realtimeStt.ts

@@ -24,24 +24,25 @@
  * when the deltas go quiet for `utteranceSilence`.
  */
 import {
-  Cause,
   Clock,
   Duration,
   Effect,
-  Encoding,
   Match,
-  Queue,
+  Option,
+  Predicate,
   Redacted,
   Ref,
   Schema,
   Stream,
 } from "effect"
-import * as Socket from "effect/unstable/socket/Socket"
+import { Base64 } from "effect/encoding"
+import * as Socket from "effect/socket/Socket"
 import * as AiError from "@effect-uai/core/AiError"
 import type { AudioFormat } from "@effect-uai/core/Audio"
 import * as JSONL from "@effect-uai/core/JSONL"
 import type { TranscriptEvent } from "@effect-uai/core/Transcript"
 import type { CommonStreamTranscribeRequest } from "@effect-uai/core/Transcriber"
+import * as WebSocketSession from "@effect-uai/core/WebSocketSession"
 import { WebSocket as WSWebSocket } from "ws"
 
 export type Config = {
@@ -55,6 +56,11 @@ export type Config = {
    * adapter delimits turns. Default 700 ms.
    */
   readonly utteranceSilence?: Duration.Duration
+  /**
+   * Build the socket yourself, for a proxy or an in-memory transport. The
+   * default attaches the bearer token through the `ws` package.
+   */
+  readonly webSocket?: Socket.WebSocketConstructor["Service"]
 }
 
 const DEFAULT_SILENCE = Duration.millis(700)
@@ -95,7 +101,7 @@ const sessionUpdateFrame = (cfg: Config) =>
   })
 
 const audioAppendFrame = (bytes: Uint8Array) =>
-  JSON.stringify({ type: "input_audio.append", audio: Encoding.encodeBase64(bytes) })
+  JSON.stringify({ type: "input_audio.append", audio: Base64.encode(bytes) })
 
 const audioEndFrame = JSON.stringify({ type: "input_audio.end" })
 
@@ -120,68 +126,73 @@ const ServerEvent = Schema.Union([
 ])
 const decodeServerEvent = Schema.decodeUnknownEffect(ServerEvent)
 
-/** Mutable turn state shared by the message handler and the silence finalizer. */
+/** Mutable turn state shared by the frame handler and the silence finalizer. */
 type TurnState = {
   readonly text: Ref.Ref<string>
   readonly lastActivityMs: Ref.Ref<number>
 }
 
-const emitFinal = (
-  queue: Queue.Queue<TranscriptEvent, Cause.Done>,
+const takeFinal = (
   state: TurnState,
   override?: string,
-): Effect.Effect<void> =>
+): Effect.Effect<TranscriptEvent | undefined> =>
   Effect.gen(function* () {
     const acc = yield* Ref.getAndSet(state.text, "")
     const text = (override !== undefined && override.length > 0 ? override : acc).trim()
-    if (text.length > 0) yield* Queue.offer(queue, { _tag: "final", text })
+    return text.length > 0 ? { _tag: "final", text } : undefined
   })
 
-const handleServerMessage =
-  (queue: Queue.Queue<TranscriptEvent, Cause.Done>, state: TurnState) => (raw: string) =>
+const frameToEvent =
+  (state: TurnState) =>
+  (raw: string): Effect.Effect<TranscriptEvent | undefined> =>
     Effect.gen(function* () {
       const json = yield* JSONL.parseSafe(raw)
-      if (json === undefined) return
+      if (json === undefined) return undefined
       const decoded = yield* decodeServerEvent(json).pipe(Effect.option)
-      if (decoded._tag === "None") return
-      yield* Match.value(decoded.value).pipe(
+      if (Option.isNone(decoded)) return undefined
+      return yield* Match.value(decoded.value).pipe(
         Match.when({ type: "transcription.text.delta" }, (m) =>
           Effect.gen(function* () {
             const now = yield* Clock.currentTimeMillis
             const next = yield* Ref.updateAndGet(state.text, (t) => t + m.text)
             yield* Ref.set(state.lastActivityMs, now)
             // Cumulative partial so the UI shows the growing sentence.
-            yield* Queue.offer(queue, { _tag: "partial", text: next })
+            return { _tag: "partial", text: next } satisfies TranscriptEvent
           }),
         ),
         // End-of-audio: commit whatever's left as the final utterance.
-        Match.when({ type: "transcription.done" }, (m) => emitFinal(queue, state, m.text)),
+        Match.when({ type: "transcription.done" }, (m) => takeFinal(state, m.text)),
         Match.when({ type: "error" }, (m) =>
-          Queue.offer(queue, {
+          Effect.succeed<TranscriptEvent>({
             _tag: "error",
             ...(m.error.code != null && { code: String(m.error.code) }),
             message: m.error.message,
           }),
         ),
         // session.created / .updated / language / segment: no user-visible event.
-        Match.orElse(() => Effect.void),
+        Match.orElse(() => Effect.succeed(undefined)),
       )
     })
 
-// Background loop: commit a synthetic final once the deltas go quiet.
-const silenceFinalizer = (
-  queue: Queue.Queue<TranscriptEvent, Cause.Done>,
+// Commits a synthetic final once the deltas go quiet; checks now, then every 150 ms.
+const silenceFinals = (
   state: TurnState,
   silence: Duration.Duration,
-): Effect.Effect<never> => {
+): Stream.Stream<TranscriptEvent> => {
   const silenceMs = Duration.toMillis(silence)
-  return Effect.gen(function* () {
-    const now = yield* Clock.currentTimeMillis
-    const last = yield* Ref.get(state.lastActivityMs)
-    const acc = yield* Ref.get(state.text)
-    if (acc.trim().length > 0 && now - last >= silenceMs) yield* emitFinal(queue, state)
-    yield* Effect.sleep("150 millis")
-  }).pipe(Effect.forever)
+  return Stream.tick("150 millis").pipe(
+    Stream.mapEffect(() =>
+      Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis
+        const last = yield* Ref.get(state.lastActivityMs)
+        const acc = yield* Ref.get(state.text)
+        return acc.trim().length > 0 && now - last >= silenceMs
+          ? yield* takeFinal(state)
+          : undefined
+      }),
+    ),
+    Stream.filter(Predicate.isNotUndefined),
+  )
 }
 
 // ---------------------------------------------------------------------------
@@ -208,49 +219,42 @@ export const streamTranscription =
     Stream.unwrap(
       Effect.gen(function* () {
         yield* ensureInputFormat(request.inputFormat)
-        const socket = yield* Socket.makeWebSocket(buildWsUrl(cfg, request.model), {
-          // Effect's Socket treats all close codes as errors by default —
-          // whitelist standard clean-close codes (1000 / 1001 / 1005).
-          closeCodeIsError: (code) => code !== 1000 && code !== 1001 && code !== 1005,
-        }).pipe(Effect.provideService(Socket.WebSocketConstructor, authedWsConstructor(cfg)))
-        const queue = yield* Queue.bounded<TranscriptEvent, Cause.Done>(64)
+        const socket = yield* Socket.makeWebSocket(buildWsUrl(cfg, request.model)).pipe(
+          Effect.provideService(
+            Socket.WebSocketConstructor,
+            cfg.webSocket ?? authedWsConstructor(cfg),
+          ),
+        )
         const state: TurnState = {
           text: yield* Ref.make(""),
           lastActivityMs: yield* Ref.make(0),
         }
-        const write = yield* socket.writer
+        const { write } = yield* socket.writer
+        const asAiError = WebSocketSession.toAiError("mistral")
 
-        // session.update first, then stream base64 PCM frames, then signal end.
-        // Fork-scoped so the Stream's downstream scope tears them down on
-        // disconnect / cancel.
-        yield* Effect.gen(function* () {
-          yield* write(sessionUpdateFrame(cfg))
-          yield* Stream.runForEach(audioIn, (bytes) => write(audioAppendFrame(bytes)))
-          yield* write(audioEndFrame)
-        }).pipe(
-          Effect.tapError((cause) =>
-            Effect.logWarning("[voxtral-realtime] audio send failed", { cause }),
-          ),
-          Effect.ignore,
-          Effect.forkScoped,
+        const frames = Stream.fromPull(Socket.readerString(socket)).pipe(
+          Stream.scoped,
+          Stream.catchIf(WebSocketSession.isCleanClose, () => Stream.empty),
+          Stream.mapError(asAiError),
+          Stream.mapEffect(frameToEvent(state)),
+          Stream.filter(Predicate.isNotUndefined),
         )
-
-        yield* silenceFinalizer(queue, state, cfg.utteranceSilence ?? DEFAULT_SILENCE).pipe(
-          Effect.forkScoped,
+        const events = Stream.merge(
+          frames,
+          silenceFinals(state, cfg.utteranceSilence ?? DEFAULT_SILENCE),
+          { haltStrategy: "left" },
         )
 
-        // `Queue.end` flushes pending events then ends the stream cleanly;
-        // `Queue.shutdown` would drop queued items and interrupt takes. A
-        // connection/read failure is logged (otherwise the stream would end
-        // silently with no transcripts).
-        yield* socket.runString(handleServerMessage(queue, state)).pipe(
-          Effect.tapError((cause) =>
-            Effect.logWarning("[voxtral-realtime] socket closed", { cause }),
+        // session.update first, then base64 PCM, then signal end. Writes wait for the reader to connect.
+        const outgoing = Stream.concat(
+          Stream.concat(
+            Stream.make(sessionUpdateFrame(cfg)),
+            Stream.map(audioIn, audioAppendFrame),
           ),
-          Effect.ensuring(Queue.end(queue)),
-          Effect.forkScoped,
-        )
+          Stream.make(audioEndFrame),
+        ).pipe(Stream.mapEffect((frame) => Effect.mapError(write(frame), asAiError)))
 
-        return Stream.fromQueue(queue)
+        // The server's close ends the transcript; the audio running out does not.
+        return Stream.merge(events, Stream.drain(outgoing), { haltStrategy: "left" })
       }),
     )