@vellumai/assistant 0.6.2 → 0.6.4

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

@@ -0,0 +1,306 @@
+/**
+ * STT provider catalog — single source of truth for provider metadata.
+ *
+ * Every STT provider is described by a {@link SttProviderEntry} that
+ * captures its canonical ID, the credential-provider name used to look up
+ * API keys, supported runtime boundaries, and telephony support mode.
+ *
+ * All other modules that need provider metadata (resolve.ts,
+ * daemon-batch-transcriber.ts, future telephony adapters) read from this
+ * catalog rather than maintaining their own hardcoded maps.
+ */
+
+import type {
+  ConversationStreamingMode,
+  SttBoundaryId,
+  SttProviderId,
+  TelephonySttMode,
+} from "../../stt/types.js";
+
+// ---------------------------------------------------------------------------
+// Telephony routing metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Strategy kind for telephony call setup.
+ *
+ * Determines how the telephony routing resolver (`telephony-stt-routing.ts`)
+ * wires the STT provider into a Twilio call:
+ *
+ * - `"conversation-relay-native"` — the provider is natively supported by
+ *   Twilio ConversationRelay. TwiML includes `transcriptionProvider` /
+ *   `speechModel` attributes and Twilio handles audio ingestion.
+ * - `"media-stream-custom"` — the provider is not natively supported by
+ *   Twilio. A `<Stream>` media-stream is opened and the daemon transcribes
+ *   audio server-side via the provider's batch API.
+ */
+export type TelephonyStrategyKind =
+  | "conversation-relay-native"
+  | "media-stream-custom";
+
+/**
+ * Twilio-native ConversationRelay provider name.
+ *
+ * These are the values Twilio accepts in the `transcriptionProvider` TwiML
+ * attribute on `<ConversationRelay>`.
+ */
+export type TwilioNativeProvider = "Deepgram" | "Google";
+
+/**
+ * Twilio-native mapping details for providers routed through
+ * ConversationRelay. Only present when `strategyKind` is
+ * `"conversation-relay-native"`.
+ */
+export interface TwilioNativeMapping {
+  /** Twilio-native provider name for the TwiML `transcriptionProvider` attribute. */
+  readonly provider: TwilioNativeProvider;
+  /**
+   * Default ASR speech model identifier, or `undefined` to use the
+   * provider's default model. Individual providers override as needed
+   * (e.g. Deepgram defaults to `"nova-3"`).
+   */
+  readonly defaultSpeechModel: string | undefined;
+}
+
+/**
+ * Telephony routing metadata — the single source of truth for how a
+ * provider is wired into Twilio call setup.
+ *
+ * The telephony routing resolver reads these fields from the catalog
+ * instead of maintaining its own hardcoded maps.
+ */
+export interface TelephonyRouting {
+  /** Which Twilio call-setup strategy this provider uses. */
+  readonly strategyKind: TelephonyStrategyKind;
+  /**
+   * Twilio-native mapping details. Present when `strategyKind` is
+   * `"conversation-relay-native"`, absent for `"media-stream-custom"`.
+   */
+  readonly twilioNativeMapping?: TwilioNativeMapping;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog entry
+// ---------------------------------------------------------------------------
+
+/**
+ * Metadata for a single STT provider.
+ */
+export interface SttProviderEntry {
+  /** Canonical provider identifier (must match an {@link SttProviderId} variant). */
+  readonly id: SttProviderId;
+
+  /**
+   * Name of the credential provider used by `getProviderKeyAsync` to
+   * retrieve the API key. Multiple STT providers may share a credential
+   * provider (e.g. a future "openai-realtime" provider would also map to
+   * `"openai"`).
+   */
+  readonly credentialProvider: string;
+
+  /**
+   * Set of runtime boundaries this provider supports. A provider may
+   * support more than one boundary (e.g. both `daemon-batch` and a future
+   * `realtime-ws` boundary).
+   */
+  readonly supportedBoundaries: ReadonlySet<SttBoundaryId>;
+
+  /**
+   * Telephony capability class — describes the provider's native
+   * audio-ingestion capability for telephony contexts.
+   */
+  readonly telephonyMode: TelephonySttMode;
+
+  /**
+   * Conversation streaming mode — describes whether and how the provider
+   * can participate in real-time conversation chat message capture
+   * (chat composer and iOS input bar).
+   *
+   * - `"realtime-ws"` — native WebSocket streaming with partial/final events.
+   * - `"incremental-batch"` — polling-based incremental batch approximation.
+   * - `"none"` — no streaming support; fall back to batch transcription.
+   */
+  readonly conversationStreamingMode: ConversationStreamingMode;
+
+  /**
+   * Whether the provider can attribute transcribed speech to distinct
+   * speakers (speaker diarization). When `true`, callers may opt in to
+   * per-utterance speaker labels via the provider's streaming/batch
+   * configuration. When `false`, speaker-label callers must fall back to
+   * single-speaker output.
+   *
+   * Flip this flag in the catalog if a provider gains diarization support;
+   * downstream code reads the capability from here via
+   * {@link supportsDiarization}.
+   */
+  readonly supportsDiarization: boolean;
+
+  /**
+   * Telephony routing metadata — describes how this provider is wired
+   * into Twilio call setup. This is the single source of truth for
+   * strategy selection and Twilio-native mapping details.
+   */
+  readonly telephonyRouting: TelephonyRouting;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog data
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider catalog entries, keyed by provider ID.
+ *
+ * To add a new STT provider:
+ * 1. Add a new variant to `SttProviderId` in `stt/types.ts`.
+ * 2. Add an entry here with the credential mapping and boundary support.
+ * 3. Wire up the adapter in `daemon-batch-transcriber.ts` (and/or a
+ *    future realtime adapter) for the boundaries the provider supports.
+ */
+const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
+  SttProviderId,
+  SttProviderEntry
+>([
+  [
+    "deepgram",
+    {
+      id: "deepgram",
+      credentialProvider: "deepgram",
+      supportedBoundaries: new Set<SttBoundaryId>([
+        "daemon-batch",
+        "daemon-streaming",
+      ]),
+      telephonyMode: "realtime-ws",
+      conversationStreamingMode: "realtime-ws",
+      supportsDiarization: true,
+      telephonyRouting: {
+        strategyKind: "conversation-relay-native",
+        twilioNativeMapping: {
+          provider: "Deepgram",
+          defaultSpeechModel: "nova-3",
+        },
+      },
+    },
+  ],
+  [
+    "google-gemini",
+    {
+      id: "google-gemini",
+      credentialProvider: "gemini",
+      supportedBoundaries: new Set<SttBoundaryId>([
+        "daemon-batch",
+        "daemon-streaming",
+      ]),
+      telephonyMode: "batch-only",
+      conversationStreamingMode: "realtime-ws",
+      supportsDiarization: false,
+      telephonyRouting: {
+        strategyKind: "conversation-relay-native",
+        twilioNativeMapping: {
+          provider: "Google",
+          defaultSpeechModel: undefined,
+        },
+      },
+    },
+  ],
+  [
+    "openai-whisper",
+    {
+      id: "openai-whisper",
+      credentialProvider: "openai",
+      supportedBoundaries: new Set<SttBoundaryId>([
+        "daemon-batch",
+        "daemon-streaming",
+      ]),
+      telephonyMode: "batch-only",
+      conversationStreamingMode: "incremental-batch",
+      supportsDiarization: false,
+      telephonyRouting: {
+        strategyKind: "media-stream-custom",
+      },
+    },
+  ],
+]);
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up a provider entry by its canonical ID.
+ *
+ * Returns `undefined` when the ID is not present in the catalog (e.g. an
+ * unknown runtime value that passed schema validation).
+ */
+export function getProviderEntry(
+  id: SttProviderId,
+): SttProviderEntry | undefined {
+  return CATALOG.get(id);
+}
+
+/**
+ * Return all catalog entries in deterministic (insertion) order.
+ */
+export function listProviderEntries(): readonly SttProviderEntry[] {
+  return [...CATALOG.values()];
+}
+
+/**
+ * Look up the credential-provider name for a given STT provider.
+ *
+ * Convenience wrapper around `getProviderEntry` for callers that only need
+ * the credential mapping. Returns `undefined` when the provider is unknown.
+ */
+export function getCredentialProvider(id: SttProviderId): string | undefined {
+  return CATALOG.get(id)?.credentialProvider;
+}
+
+/**
+ * Check whether a provider supports a specific runtime boundary.
+ *
+ * Returns `false` for unknown provider IDs.
+ */
+export function supportsBoundary(
+  id: SttProviderId,
+  boundary: SttBoundaryId,
+): boolean {
+  return CATALOG.get(id)?.supportedBoundaries.has(boundary) ?? false;
+}
+
+/**
+ * Check whether a provider supports speaker diarization.
+ *
+ * Returns `false` for unknown provider IDs. Callers use this to decide
+ * whether to request speaker labels from the provider's streaming or
+ * batch configuration.
+ */
+export function supportsDiarization(id: SttProviderId): boolean {
+  return CATALOG.get(id)?.supportsDiarization ?? false;
+}
+
+/**
+ * Return all canonical provider IDs in deterministic (insertion) order.
+ */
+export function listProviderIds(): readonly SttProviderId[] {
+  return [...CATALOG.keys()];
+}
+
+/**
+ * Return the deduplicated set of credential-provider names used by STT
+ * providers, in deterministic (first-seen) order.
+ *
+ * Multiple STT providers may share a single credential provider (e.g.
+ * `openai-whisper` and a future `openai-realtime` both map to `"openai"`).
+ * This helper deduplicates so that callers composing API-key provider
+ * lists do not produce duplicate entries.
+ */
+export function listCredentialProviderNames(): readonly string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const entry of CATALOG.values()) {
+    if (!seen.has(entry.credentialProvider)) {
+      seen.add(entry.credentialProvider);
+      result.push(entry.credentialProvider);
+    }
+  }
+  return result;
+}

package/src/providers/speech-to-text/resolve.ts

@@ -1,9 +1,389 @@
+import { getConfig } from "../../config/loader.js";
 import { getProviderKeyAsync } from "../../security/secure-keys.js";
-import { OpenAIWhisperProvider } from "./openai-whisper.js";
-import type { SpeechToTextProvider } from "./types.js";
+import { createDaemonBatchTranscriber } from "../../stt/daemon-batch-transcriber.js";
+import type {
+  BatchTranscriber,
+  StreamingTranscriber,
+  SttProviderId,
+} from "../../stt/types.js";
+import { getLogger } from "../../util/logger.js";
+import {
+  getCredentialProvider,
+  getProviderEntry,
+  supportsBoundary,
+  supportsDiarization,
+} from "./provider-catalog.js";
 
-export async function resolveSpeechToTextProvider(): Promise<SpeechToTextProvider | null> {
-  const apiKey = await getProviderKeyAsync("openai");
-  if (!apiKey) return null;
-  return new OpenAIWhisperProvider(apiKey);
+const log = getLogger("stt-resolver");
+
+// ---------------------------------------------------------------------------
+// Batch transcriber resolver (existing public API — unchanged contract)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a `BatchTranscriber` for daemon-hosted batch transcription.
+ *
+ * Reads `services.stt.provider` from the assistant config to determine which
+ * STT provider to use, then looks up the corresponding credential via the
+ * provider catalog. Credential lookup is centralized here (an authorized
+ * secure-keys importer) so callers don't need to import secure-keys directly.
+ *
+ * Returns `null` when:
+ * - The configured provider is not in the catalog.
+ * - The configured provider doesn't support the `daemon-batch` boundary.
+ * - No credentials are configured for the resolved provider.
+ */
+export async function resolveBatchTranscriber(): Promise<BatchTranscriber | null> {
+  const config = getConfig();
+  const provider = config.services.stt.provider;
+
+  // Look up credential provider via the catalog.
+  const credentialProviderName = getCredentialProvider(
+    provider as SttProviderId,
+  );
+  if (!credentialProviderName) {
+    return null;
+  }
+
+  // Verify the provider supports the daemon-batch boundary.
+  if (!supportsBoundary(provider as SttProviderId, "daemon-batch")) {
+    return null;
+  }
+
+  const apiKey = await getProviderKeyAsync(credentialProviderName);
+  return createDaemonBatchTranscriber(apiKey, provider as SttProviderId);
+}
+
+// ---------------------------------------------------------------------------
+// Telephony capability resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of resolving whether the configured `services.stt` provider is
+ * eligible for telephony call ingestion.
+ */
+export type TelephonySttCapability =
+  | {
+      /** The configured provider supports telephony. */
+      status: "supported";
+      providerId: SttProviderId;
+      /** How the provider participates in real-time call ingestion. */
+      telephonyMode: "realtime-ws" | "batch-only";
+    }
+  | {
+      /** The configured provider does not support telephony. */
+      status: "unsupported";
+      providerId: SttProviderId;
+      reason: string;
+    }
+  | {
+      /** The configured provider is unknown or not in the catalog. */
+      status: "unconfigured";
+      reason: string;
+    }
+  | {
+      /** The provider is eligible but missing credentials. */
+      status: "missing-credentials";
+      providerId: SttProviderId;
+      credentialProvider: string;
+      reason: string;
+    };
+
+/**
+ * Validate whether the configured `services.stt` provider is eligible for
+ * future real-time telephony call ingestion.
+ *
+ * This resolver does **not** create a live transcriber — it only validates
+ * that the configuration, catalog entry, and credentials are all in order.
+ * The actual wiring is deferred to a future media-stream call adapter PR.
+ *
+ * Callers can branch on the discriminated `status` field:
+ * - `"supported"` — the provider is telephony-eligible and credentials exist.
+ * - `"unsupported"` — the provider exists but has `telephonyMode: "none"`.
+ * - `"unconfigured"` — the provider is unknown or missing from the catalog.
+ * - `"missing-credentials"` — the provider is eligible but has no API key.
+ */
+export async function resolveTelephonySttCapability(): Promise<TelephonySttCapability> {
+  const config = getConfig();
+  const provider = config.services.stt.provider;
+
+  const entry = getProviderEntry(provider as SttProviderId);
+  if (!entry) {
+    return {
+      status: "unconfigured",
+      reason: `STT provider "${provider}" is not in the provider catalog`,
+    };
+  }
+
+  if (entry.telephonyMode === "none") {
+    return {
+      status: "unsupported",
+      providerId: entry.id,
+      reason: `STT provider "${entry.id}" does not support telephony`,
+    };
+  }
+
+  // Provider is telephony-eligible — verify credentials exist.
+  const apiKey = await getProviderKeyAsync(entry.credentialProvider);
+  if (!apiKey) {
+    return {
+      status: "missing-credentials",
+      providerId: entry.id,
+      credentialProvider: entry.credentialProvider,
+      reason: `No API key configured for credential provider "${entry.credentialProvider}"`,
+    };
+  }
+
+  return {
+    status: "supported",
+    providerId: entry.id,
+    telephonyMode: entry.telephonyMode,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Conversation streaming capability resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of resolving whether the configured `services.stt` provider
+ * supports conversation streaming for chat message capture.
+ */
+export type ConversationStreamingSttCapability =
+  | {
+      /** The configured provider supports conversation streaming. */
+      status: "supported";
+      providerId: SttProviderId;
+      /** How the provider implements conversation streaming. */
+      streamingMode: "realtime-ws" | "incremental-batch";
+    }
+  | {
+      /** The configured provider does not support conversation streaming. */
+      status: "unsupported";
+      providerId: SttProviderId;
+      reason: string;
+    }
+  | {
+      /** The configured provider is unknown or not in the catalog. */
+      status: "unconfigured";
+      reason: string;
+    }
+  | {
+      /** The provider is eligible but missing credentials. */
+      status: "missing-credentials";
+      providerId: SttProviderId;
+      credentialProvider: string;
+      reason: string;
+    };
+
+/**
+ * Validate whether the configured `services.stt` provider supports
+ * conversation streaming for chat message capture (chat composer and
+ * iOS input bar).
+ *
+ * This resolver does **not** create a live streaming session — it only
+ * validates that the configuration, catalog entry, and credentials are
+ * all in order. The actual session creation is handled by the runtime
+ * session orchestrator (PR 5).
+ *
+ * Callers can branch on the discriminated `status` field:
+ * - `"supported"` — the provider supports streaming and credentials exist.
+ * - `"unsupported"` — the provider exists but has
+ *   `conversationStreamingMode: "none"`.
+ * - `"unconfigured"` — the provider is unknown or missing from the catalog.
+ * - `"missing-credentials"` — the provider is eligible but has no API key.
+ */
+export async function resolveConversationStreamingSttCapability(): Promise<ConversationStreamingSttCapability> {
+  const config = getConfig();
+  const provider = config.services.stt.provider;
+
+  const entry = getProviderEntry(provider as SttProviderId);
+  if (!entry) {
+    return {
+      status: "unconfigured",
+      reason: `STT provider "${provider}" is not in the provider catalog`,
+    };
+  }
+
+  if (entry.conversationStreamingMode === "none") {
+    return {
+      status: "unsupported",
+      providerId: entry.id,
+      reason: `STT provider "${entry.id}" does not support conversation streaming`,
+    };
+  }
+
+  // Provider is streaming-eligible — verify credentials exist.
+  const apiKey = await getProviderKeyAsync(entry.credentialProvider);
+  if (!apiKey) {
+    return {
+      status: "missing-credentials",
+      providerId: entry.id,
+      credentialProvider: entry.credentialProvider,
+      reason: `No API key configured for credential provider "${entry.credentialProvider}"`,
+    };
+  }
+
+  return {
+    status: "supported",
+    providerId: entry.id,
+    streamingMode: entry.conversationStreamingMode,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Streaming transcriber resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Speaker diarization preference for a streaming session.
+ *
+ * - `"off"` (default): never request diarization. Behavior unchanged from
+ *   pre-diarization callers.
+ * - `"preferred"`: enable diarization when the configured provider supports
+ *   it; silently proceed without it on non-capable providers.
+ * - `"required"`: enable diarization on capable providers; return `null` and
+ *   log a warning on non-capable providers. Callers that pass `"required"`
+ *   are expected to surface a clear error to the user.
+ */
+export type DiarizePreference = "preferred" | "required" | "off";
+
+/**
+ * Options for resolving a streaming transcriber.
+ */
+export interface ResolveStreamingTranscriberOptions {
+  /** Audio sample rate in Hz from the client WebSocket connection. */
+  sampleRate?: number;
+  /**
+   * Speaker diarization preference. Default: `"off"`.
+   *
+   * See {@link DiarizePreference} for semantics.
+   */
+  diarize?: DiarizePreference;
+}
+
+/**
+ * Resolve a `StreamingTranscriber` for daemon-hosted streaming transcription.
+ *
+ * Reads `services.stt.provider` from the assistant config to determine which
+ * STT provider to use, verifies it supports the `daemon-streaming` boundary,
+ * and constructs the appropriate streaming adapter. Credential lookup is
+ * centralized here (an authorized secure-keys importer) so callers don't
+ * need to import secure-keys directly.
+ *
+ * Returns `null` when:
+ * - The configured provider is not in the catalog.
+ * - The configured provider doesn't support the `daemon-streaming` boundary.
+ * - No credentials are configured for the resolved provider.
+ * - No streaming adapter exists for the configured provider.
+ * - `diarize` is `"required"` but the configured provider cannot diarize.
+ */
+export async function resolveStreamingTranscriber(
+  options: ResolveStreamingTranscriberOptions = {},
+): Promise<StreamingTranscriber | null> {
+  const config = getConfig();
+  const provider = config.services.stt.provider;
+  const diarizePreference: DiarizePreference = options.diarize ?? "off";
+
+  // Look up credential provider via the catalog.
+  const credentialProviderName = getCredentialProvider(
+    provider as SttProviderId,
+  );
+  if (!credentialProviderName) {
+    return null;
+  }
+
+  // Verify the provider supports the daemon-streaming boundary.
+  if (!supportsBoundary(provider as SttProviderId, "daemon-streaming")) {
+    return null;
+  }
+
+  // Resolve diarization capability against the catalog. For `"required"`
+  // callers, bail early (with a warning) when the configured provider can't
+  // diarize so the caller can surface a clear error to the user.
+  const providerSupportsDiarization = supportsDiarization(
+    provider as SttProviderId,
+  );
+  if (diarizePreference === "required" && !providerSupportsDiarization) {
+    log.warn(
+      { providerId: provider },
+      "diarization is required but configured STT provider does not support it",
+    );
+    return null;
+  }
+  const enableDiarization =
+    (diarizePreference === "preferred" || diarizePreference === "required") &&
+    providerSupportsDiarization;
+
+  const apiKey = await getProviderKeyAsync(credentialProviderName);
+  if (!apiKey) {
+    return null;
+  }
+
+  return createStreamingTranscriber(apiKey, provider as SttProviderId, {
+    sampleRate: options.sampleRate,
+    diarize: enableDiarization,
+  });
+}
+
+/**
+ * Options forwarded to individual streaming adapter constructors.
+ */
+interface CreateStreamingTranscriberOptions {
+  sampleRate?: number;
+  /**
+   * Whether to enable speaker diarization on providers that support it.
+   * Only forwarded to provider adapters that accept a diarize option
+   * (e.g. Deepgram). Silently ignored by adapters without diarization
+   * support.
+   */
+  diarize?: boolean;
+}
+
+/**
+ * Create a `StreamingTranscriber` for the given provider.
+ *
+ * Uses lazy imports so the adapter modules are only loaded when needed,
+ * keeping the module graph lightweight for callers that only need batch
+ * transcription.
+ *
+ * Returns `null` for providers that do not have a streaming adapter.
+ */
+async function createStreamingTranscriber(
+  apiKey: string,
+  providerId: SttProviderId,
+  options: CreateStreamingTranscriberOptions = {},
+): Promise<StreamingTranscriber | null> {
+  switch (providerId) {
+    case "deepgram": {
+      const { DeepgramRealtimeTranscriber } =
+        await import("./deepgram-realtime.js");
+      return new DeepgramRealtimeTranscriber(apiKey, {
+        sampleRate: options.sampleRate,
+        ...(options.diarize ? { diarize: true } : {}),
+      });
+    }
+    case "google-gemini": {
+      // Gemini does not support speaker diarization; the diarize option is
+      // silently ignored here.
+      const { GoogleGeminiLiveStreamingTranscriber } =
+        await import("./google-gemini-live-stream.js");
+      return new GoogleGeminiLiveStreamingTranscriber(apiKey, {
+        pcmSampleRate: options.sampleRate,
+      });
+    }
+    case "openai-whisper": {
+      // OpenAI Whisper does not support speaker diarization; the diarize
+      // option is silently ignored here.
+      const { OpenAIWhisperStreamingTranscriber } =
+        await import("./openai-whisper-stream.js");
+      return new OpenAIWhisperStreamingTranscriber(apiKey, {
+        pcmSampleRate: options.sampleRate,
+      });
+    }
+    default: {
+      const _exhaustive: never = providerId;
+      return null;
+    }
+  }
 }