@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/providers/speech-to-text/__tests__/deepgram-flux-frames.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   buildFluxQueryParams,
+  fluxModelForLanguage,
   parseFluxFrame,
 } from "../deepgram-flux-frames.js";
 
@@ -431,3 +432,44 @@ describe("buildFluxQueryParams", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// fluxModelForLanguage
+// ---------------------------------------------------------------------------
+
+describe("fluxModelForLanguage", () => {
+  test("unset and English select the English model with no hint", () => {
+    for (const language of [undefined, "", "en", "en-US", "EN"]) {
+      expect(fluxModelForLanguage(language)).toEqual({
+        model: "flux-general-en",
+      });
+    }
+  });
+
+  test("multi selects code-switching, which takes no hint", () => {
+    // A hint would tell Flux the answer; omitting it is what asks it to
+    // detect and follow a speaker between languages.
+    expect(fluxModelForLanguage("multi")).toEqual({
+      model: "flux-general-multi",
+    });
+  });
+
+  test("a supported non-English language hints the multilingual model", () => {
+    expect(fluxModelForLanguage("es")).toEqual({
+      model: "flux-general-multi",
+      languageHint: "es",
+    });
+    expect(fluxModelForLanguage("pt-BR")).toEqual({
+      model: "flux-general-multi",
+      languageHint: "pt",
+    });
+  });
+
+  test("a language Flux cannot serve resolves to nothing", () => {
+    // The caller refuses instead: the English model would return fluent
+    // nonsense that the transcript gives no sign of.
+    for (const language of ["ko", "zh", "ta", "sw"]) {
+      expect(fluxModelForLanguage(language)).toBeNull();
+    }
+  });
+});

package/src/providers/speech-to-text/__tests__/deepgram-flux-realtime.test.ts

@@ -622,4 +622,140 @@ describe("DeepgramFluxRealtimeTranscriber", () => {
     expect(transcriber.providerId).toBe("deepgram-flux");
     expect(transcriber.boundaryId).toBe("daemon-streaming");
   });
+
+  // ─────────────────────────────────────────────────────────────────
+  // Relay transport seams
+  // ─────────────────────────────────────────────────────────────────
+
+  describe("relay transport", () => {
+    const RELAY_OPTIONS = {
+      baseUrl: "wss://gateway.test",
+      path: "/v2/speech/stt/stream",
+      queryAuth: true,
+      omitModelParam: true,
+      nativeContract: true,
+      language: "multi",
+    };
+
+    test("dials the relay path with query auth and the native contract", async () => {
+      await startSession(RELAY_OPTIONS);
+
+      const url = new URL(dialedUrls[0]!);
+      expect(url.origin).toBe("wss://gateway.test");
+      expect(url.pathname).toBe("/v2/speech/stt/stream");
+      expect(url.searchParams.get("contract")).toBe("flux");
+      expect(url.searchParams.get("key")).toBe(TEST_API_KEY);
+      expect(url.searchParams.get("language")).toBe("multi");
+
+      // The relay derives and prices the Flux model itself, and rejects a
+      // client-selected one.
+      expect(url.searchParams.has("model")).toBe(false);
+
+      // Query auth carries the credential, so no Authorization header.
+      expect(dialedOptions[0]).toBeUndefined();
+    });
+
+    test("still sends the turn-detection tuning to the relay", async () => {
+      // Without eager_eot_threshold reaching Deepgram there are no eager
+      // turn ends at all, which is the whole point of the native contract.
+      await startSession({
+        ...RELAY_OPTIONS,
+        // eot tuning comes from liveVoice.flux, not the options.
+      });
+
+      const url = new URL(dialedUrls[0]!);
+      expect(url.searchParams.has("eot_threshold")).toBe(true);
+      expect(url.searchParams.get("encoding")).toBe("linear16");
+      expect(url.searchParams.get("sample_rate")).toBe("16000");
+    });
+
+    test("derives the model from the language when none is pinned", async () => {
+      // The relay does this mapping server-side; the direct path has to do it
+      // here, or a non-English session silently runs the English model.
+      await startSession({ language: "es" });
+
+      const url = new URL(dialedUrls[0]!);
+      expect(url.searchParams.get("model")).toBe("flux-general-multi");
+      expect(url.searchParams.get("language_hint")).toBe("es");
+    });
+
+    test("code-switching takes the multilingual model and no hint", async () => {
+      await startSession({ language: "multi" });
+
+      const url = new URL(dialedUrls[0]!);
+      expect(url.searchParams.get("model")).toBe("flux-general-multi");
+      expect(url.searchParams.has("language_hint")).toBe(false);
+    });
+
+    test("the relay path sends neither model nor hint", async () => {
+      // velay derives both from the language it is sent, and rejects a
+      // client-selected model.
+      await startSession({ ...RELAY_OPTIONS, language: "es" });
+
+      const url = new URL(dialedUrls[0]!);
+      expect(url.searchParams.has("model")).toBe(false);
+      expect(url.searchParams.has("language_hint")).toBe(false);
+      expect(url.searchParams.get("language")).toBe("es");
+    });
+
+    test("keeps the direct Deepgram dial unchanged", async () => {
+      await startSession();
+
+      const url = new URL(dialedUrls[0]!);
+      expect(url.origin).toBe("wss://api.deepgram.com");
+      expect(url.pathname).toBe("/v2/listen");
+      expect(url.searchParams.has("contract")).toBe(false);
+      expect(url.searchParams.has("key")).toBe(false);
+      expect(url.searchParams.has("language")).toBe(false);
+      expect(url.searchParams.get("model")).toBe("flux-general-en");
+      expect(dialedOptions[0]?.headers?.Authorization).toBe(
+        `Token ${TEST_API_KEY}`,
+      );
+    });
+
+    test("redacts the query-auth credential from the dial log", async () => {
+      await startSession(RELAY_OPTIONS);
+
+      const opened = infoLogs.find((entry) =>
+        entry.message.includes("Opening Deepgram Flux session"),
+      );
+      const logged = String((opened?.data as { url?: string })?.url ?? "");
+      expect(logged).not.toContain(TEST_API_KEY);
+      expect(logged).toContain("key=***");
+    });
+
+    test("hands frames the Flux parser makes nothing of to the wrapper", async () => {
+      // This is how velay_error reaches the managed wrapper: it rides the
+      // same socket but is not a Flux frame.
+      const unhandled: Record<string, unknown>[] = [];
+      await startSession({
+        ...RELAY_OPTIONS,
+        onUnhandledFrame: (frame) => unhandled.push(frame),
+      });
+
+      mockWs.simulateMessage(
+        JSON.stringify({
+          type: "velay_error",
+          code: "insufficient_credits",
+          detail: "top up",
+        }),
+      );
+
+      expect(unhandled).toEqual([
+        { type: "velay_error", code: "insufficient_credits", detail: "top up" },
+      ]);
+    });
+
+    test("does not report real Flux frames as unhandled", async () => {
+      const unhandled: Record<string, unknown>[] = [];
+      await startSession({
+        ...RELAY_OPTIONS,
+        onUnhandledFrame: (frame) => unhandled.push(frame),
+      });
+
+      mockWs.simulateMessage(turnInfoFrame("EndOfTurn", { transcript: "hi" }));
+
+      expect(unhandled).toEqual([]);
+    });
+  });
 });

package/src/providers/speech-to-text/__tests__/provider-catalog.test.ts

@@ -1,14 +1,20 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  baseModelFamilyFor,
   batchBoundaryGapReason,
   getCredentialProvider,
   getProviderEntry,
   listCredentialProviderNames,
   listProviderEntries,
   listProviderIds,
+  listProviderModelFamilies,
+  listSelectableProviderIds,
+  resolveSttCatalogKey,
+  sttConfigForCatalogKey,
   supportsBoundary,
   supportsDiarization,
+  supportsProviderTurnDetection,
 } from "../provider-catalog.js";
 
 // ---------------------------------------------------------------------------
@@ -257,3 +263,117 @@ describe("connection-based providers", () => {
     }
   });
 });
+
+describe("model families", () => {
+  test("flux rows are variants, not separately selectable providers", () => {
+    // The whole point of folding these back: a model choice must not cost a
+    // provider enum entry and a picker row.
+    for (const id of ["deepgram-flux", "vellum-flux"] as const) {
+      expect(getProviderEntry(id)?.variantOf).toBeDefined();
+      expect(listSelectableProviderIds()).not.toContain(id);
+    }
+    expect(listSelectableProviderIds()).toEqual(
+      expect.arrayContaining(["deepgram", "vellum"]),
+    );
+  });
+
+  test("a provider plus model family resolves to the variant row", () => {
+    expect(
+      resolveSttCatalogKey({
+        provider: "deepgram",
+        providers: { deepgram: { model: "flux" } },
+      }),
+    ).toBe("deepgram-flux");
+    expect(
+      resolveSttCatalogKey({
+        provider: "vellum",
+        providers: { vellum: { model: "flux" } },
+      }),
+    ).toBe("vellum-flux");
+  });
+
+  test("no model, or one the provider does not offer, resolves to the base row", () => {
+    expect(resolveSttCatalogKey({ provider: "deepgram" })).toBe("deepgram");
+    expect(
+      resolveSttCatalogKey({
+        provider: "deepgram",
+        providers: { deepgram: { model: "nova-3" } },
+      }),
+    ).toBe("deepgram");
+    // Inert rather than fatal: a family a provider does not implement falls
+    // back instead of resolving nothing.
+    expect(
+      resolveSttCatalogKey({
+        provider: "openai-whisper",
+        providers: { "openai-whisper": { model: "flux" } },
+      }),
+    ).toBe("openai-whisper");
+  });
+
+  test("a model set on another provider's entry does not leak", () => {
+    expect(
+      resolveSttCatalogKey({
+        provider: "deepgram",
+        providers: { vellum: { model: "flux" } },
+      }),
+    ).toBe("deepgram");
+  });
+
+  test("names the base family so a stale variant model can be overwritten", () => {
+    // Substituting away from a variant has to write something: leaving the
+    // old model behind resolves straight back to the variant on next load.
+    expect(baseModelFamilyFor("vellum")).toBe("nova-3");
+    expect(baseModelFamilyFor("deepgram")).toBe("nova-3");
+    // Nothing to write, and no variant that could have left a stale value.
+    expect(baseModelFamilyFor("openai-whisper")).toBeUndefined();
+    expect(baseModelFamilyFor("vellum-flux")).toBeUndefined();
+  });
+
+  test("round-trips a resolved key back to the config that selects it", () => {
+    // Anything persisting a resolved provider needs this: the key itself is
+    // not a valid services.stt.provider value.
+    expect(sttConfigForCatalogKey("vellum-flux")).toEqual({
+      provider: "vellum",
+      model: "flux",
+    });
+    expect(sttConfigForCatalogKey("deepgram")).toEqual({
+      provider: "deepgram",
+    });
+  });
+
+  test("only providers with variants advertise families", () => {
+    expect(listProviderModelFamilies("deepgram")).toEqual(["nova-3", "flux"]);
+    expect(listProviderModelFamilies("openai-whisper")).toEqual([]);
+    expect(listProviderModelFamilies("deepgram-flux")).toEqual([]);
+  });
+});
+
+describe("vellum-flux (managed Flux)", () => {
+  test("shares the vellum connection rather than a second credential", () => {
+    expect(getProviderEntry("vellum-flux")?.credentialProvider).toBe("vellum");
+    expect(listCredentialProviderNames()).not.toContain("vellum-flux");
+  });
+
+  test("is streaming-only, like the BYOK Flux entry", () => {
+    expect(supportsBoundary("vellum-flux", "daemon-streaming")).toBe(true);
+    expect(supportsBoundary("vellum-flux", "daemon-batch")).toBe(false);
+  });
+
+  test("decides end-of-turn itself, unlike plain vellum", () => {
+    // The relay is dialed with contract=flux, so Flux's turn events survive.
+    expect(supportsProviderTurnDetection("vellum-flux")).toBe(true);
+    expect(supportsProviderTurnDetection("vellum")).toBe(false);
+  });
+
+  test("stays off telephony", () => {
+    // The relay maps Finalize onto CloseStream and utterance-boundary finals
+    // are a nova-3 concept, so calls stay on `vellum`.
+    expect(getProviderEntry("vellum-flux")?.telephonyMode).toBe("none");
+  });
+
+  test("exposes a language picker, unlike BYOK Flux", () => {
+    // The relay picks flux-general-en or flux-general-multi from the language
+    // it is sent, so the selection is meaningful here.
+    expect(getProviderEntry("vellum-flux")?.languageSelection).toBe("manual");
+  });
+});