@broberg/ai-sdk 0.38.0 → 0.39.0

package/dist/index.d.ts

@@ -39,6 +39,18 @@ declare function classifyRegionName(name: string | undefined): Region;
  *  is it?" — a narrower question than "where will my call go?". */
 declare function regionOfProvider(provider: string): Region;
 
+/** One dictionary entry. `alias` says it differently; `ipa` says it precisely. */
+interface Pronunciation {
+    /** The word as it appears in the text. Matched whole-word, case-insensitively. */
+    word: string;
+    /** Say this instead. Azure `<sub alias>`; ElevenLabs plain substitution. */
+    alias?: string;
+    /** IPA phonemes. Azure `<phoneme alphabet="ipa" ph>`. ElevenLabs cannot do this. */
+    ipa?: string;
+    /** Reserved for a future per-entry language switch; carried but not yet emitted. */
+    lang?: string;
+}
+
 /** How a call reaches the model. `http` = provider REST API; `subprocess` = local
  *  `claude -p` CLI (Max plan, costUsd 0). */
 type Transport = "http" | "subprocess";
@@ -423,6 +435,7 @@ interface PodcastResult {
     mimeType: string;
     usage: Usage;
 }
+
 interface TtsRequest {
     text: string;
     voiceId: string;
@@ -432,6 +445,14 @@ interface TtsRequest {
     format?: string;
     /** Speaking-rate multiplier (Azure): 1 = normal, 0.9 = 10% slower, 1.1 = faster. ElevenLabs ignores it. */
     rate?: number;
+    /** F051 — pronunciation dictionary. A Danish voice says English jargon wrongly:
+     *  measured on da-DK, "AI" comes out as the word "aj", "native" as "nativ".
+     *
+     *  Azure renders these as SSML (`<sub alias>` / `<phoneme alphabet="ipa" ph>`);
+     *  ElevenLabs has no SSML and can only apply `alias`. **This is the CONTROLLED DOOR
+     *  into SSML** — the substitution happens adapter-side AFTER the text is escaped, so
+     *  `text` can never inject markup, and `alias`/`ipa` are escaped too. */
+    pronunciations?: Pronunciation[];
     spec: TierSpec;
 }
 interface BatchRequestItem {
@@ -1807,6 +1828,24 @@ declare const ttsInputSchema: z.ZodObject<{
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     text: z.ZodString;
     voice: z.ZodString;
+    /** F051 — see TtsRequest.pronunciations. The alias/ipa exclusivity is enforced in
+     *  the adapter, not here: the message must name the provider that cannot do it. */
+    pronunciations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        word: z.ZodString;
+        alias: z.ZodOptional<z.ZodString>;
+        ipa: z.ZodOptional<z.ZodString>;
+        lang: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        word: string;
+        alias?: string | undefined;
+        ipa?: string | undefined;
+        lang?: string | undefined;
+    }, {
+        word: string;
+        alias?: string | undefined;
+        ipa?: string | undefined;
+        lang?: string | undefined;
+    }>, "many">>;
     /** F037: voice to use if `voice` is one we know the provider has retired. Without
      *  it a retired voice throws VoiceUnavailableError rather than reaching the API.
      *
@@ -1838,8 +1877,14 @@ declare const ttsInputSchema: z.ZodObject<{
     })[] | undefined;
     labels?: Record<string, string> | undefined;
     format?: string | undefined;
-    voiceFallback?: string | undefined;
     lang?: string | undefined;
+    pronunciations?: {
+        word: string;
+        alias?: string | undefined;
+        ipa?: string | undefined;
+        lang?: string | undefined;
+    }[] | undefined;
+    voiceFallback?: string | undefined;
     rate?: number | undefined;
 }, {
     text: string;
@@ -1858,8 +1903,14 @@ declare const ttsInputSchema: z.ZodObject<{
     })[] | undefined;
     labels?: Record<string, string> | undefined;
     format?: string | undefined;
-    voiceFallback?: string | undefined;
     lang?: string | undefined;
+    pronunciations?: {
+        word: string;
+        alias?: string | undefined;
+        ipa?: string | undefined;
+        lang?: string | undefined;
+    }[] | undefined;
+    voiceFallback?: string | undefined;
     rate?: number | undefined;
 }>;
 declare const aiConfigSchema: z.ZodObject<{
@@ -2251,8 +2302,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.38.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.38.0";
+declare const VERSION: "0.39.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.39.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.

package/dist/index.js

@@ -1547,6 +1547,47 @@ function mistralAdapter(config = {}) {
   return { ...base, ocr, moderate, embedding, transcribe, batchSubmit, batchStatus, batchResults };
 }
 
+// src/providers/pronunciation.ts
+function xmlEscape(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function assertPronunciations(list, provider) {
+  for (const p of list ?? []) {
+    if (!p.word.trim()) {
+      throw new Error(`${provider} adapter: a pronunciation entry has an empty "word".`);
+    }
+    if (p.alias !== void 0 && p.ipa !== void 0) {
+      throw new Error(
+        `${provider} adapter: pronunciation "${p.word}" sets BOTH alias and ipa. They are different instructions \u2014 alias says it differently, ipa says it precisely. Pick one.`
+      );
+    }
+    if (p.alias === void 0 && p.ipa === void 0) {
+      throw new Error(
+        `${provider} adapter: pronunciation "${p.word}" sets neither alias nor ipa, so there is nothing to say instead.`
+      );
+    }
+  }
+}
+function applyPronunciations(haystack, list, render, escape = (s) => s) {
+  const entries = (list ?? []).filter((p) => p.word.trim().length > 0);
+  if (entries.length === 0) return haystack;
+  const sorted = [...entries].sort((a, b) => escape(b.word).length - escape(a.word).length);
+  const byLower = /* @__PURE__ */ new Map();
+  for (const p of sorted) {
+    const k = escape(p.word).toLowerCase();
+    if (!byLower.has(k)) byLower.set(k, p);
+  }
+  const alternation = sorted.map((p) => escapeRegex(escape(p.word))).join("|");
+  const re = new RegExp(`(?<![\\w-])(${alternation})(?![\\w-])`, "gi");
+  return haystack.replace(re, (matched) => {
+    const entry = byLower.get(matched.toLowerCase());
+    return entry ? render(entry, matched) : matched;
+  });
+}
+
 // src/providers/elevenlabs.ts
 var ELEVENLABS_PRICE_PER_1K_CHARS = 0.15;
 var ELEVENLABS_DANISH_VOICES = {
@@ -1559,6 +1600,17 @@ var ELEVENLABS_DANISH_VOICES = {
 function resolveVoice(nameOrId) {
   return ELEVENLABS_DANISH_VOICES[nameOrId] ?? nameOrId;
 }
+function ttsText(req) {
+  assertPronunciations(req.pronunciations, "elevenlabs");
+  for (const p of req.pronunciations ?? []) {
+    if (p.ipa !== void 0) {
+      throw new Error(
+        `elevenlabs adapter: pronunciation "${p.word}" uses ipa, which needs SSML \u2014 ElevenLabs has none. Use { alias } here, or route this call to azure.`
+      );
+    }
+  }
+  return applyPronunciations(req.text, req.pronunciations, (p) => p.alias);
+}
 function elevenlabsAdapter(config = {}) {
   const baseUrl = config.baseUrl ?? "https://api.elevenlabs.io/v1";
   const fetchImpl = config.fetch ?? fetch;
@@ -1602,7 +1654,7 @@ function elevenlabsAdapter(config = {}) {
     const res = await fetchImpl(`${baseUrl}/text-to-speech/${req.voiceId}`, {
       method: "POST",
       headers: { "xi-api-key": key(), "content-type": "application/json", accept: "audio/mpeg" },
-      body: JSON.stringify({ text: req.text, model_id: model })
+      body: JSON.stringify({ text: ttsText(req), model_id: model })
     });
     if (!res.ok) {
       const body = await res.text().catch(() => "");
@@ -1662,9 +1714,6 @@ function listAzureDanishVoices() {
 function resolveAzureVoice(nameOrVoice) {
   return AZURE_DANISH_VOICES[nameOrVoice] ?? nameOrVoice;
 }
-function xmlEscape(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
-}
 function localeOf(voice) {
   const parts = voice.split("-");
   return parts.length >= 2 ? `${parts[0]}-${parts[1]}` : "en-US";
@@ -1710,7 +1759,13 @@ function azureAdapter(config = {}) {
     const voice = resolveAzureVoice(req.voiceId);
     const lang = req.lang ?? localeOf(voice);
     const format = req.format ?? DEFAULT_FORMAT;
-    const escaped = xmlEscape(req.text);
+    assertPronunciations(req.pronunciations, "azure");
+    const escaped = applyPronunciations(
+      xmlEscape(req.text),
+      req.pronunciations,
+      (p, matched) => p.ipa !== void 0 ? `<phoneme alphabet='ipa' ph='${xmlEscape(p.ipa)}'>${matched}</phoneme>` : `<sub alias='${xmlEscape(p.alias)}'>${matched}</sub>`,
+      xmlEscape
+    );
     const effRate = req.rate ?? AZURE_DANISH_VOICE_LIST.find((v) => v.voiceId === voice)?.defaultRate;
     const inner = effRate != null && effRate !== 1 ? `<prosody rate='${effRate}'>${escaped}</prosody>` : escaped;
     const ssml = `<speak version='1.0' xml:lang='${lang}'><voice name='${voice}'>${inner}</voice></speak>`;
@@ -3023,9 +3078,18 @@ var podcastInputSchema = z.object({
   format: z.string().optional(),
   ...callOptions
 });
+var pronunciationSchema = z.object({
+  word: z.string(),
+  alias: z.string().optional(),
+  ipa: z.string().optional(),
+  lang: z.string().optional()
+});
 var ttsInputSchema = z.object({
   text: z.string(),
   voice: z.string(),
+  /** F051 — see TtsRequest.pronunciations. The alias/ipa exclusivity is enforced in
+   *  the adapter, not here: the message must name the provider that cannot do it. */
+  pronunciations: z.array(pronunciationSchema).optional(),
   /** F037: voice to use if `voice` is one we know the provider has retired. Without
    *  it a retired voice throws VoiceUnavailableError rather than reaching the API.
    *
@@ -3067,8 +3131,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.38.0";
-var SDK_TAG = "@broberg/ai-sdk@0.38.0";
+var VERSION = "0.39.0";
+var SDK_TAG = "@broberg/ai-sdk@0.39.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {
@@ -3611,7 +3675,15 @@ function createAI(config = {}) {
         invoke: async (spec) => {
           const adapter = pickProvider(spec.provider);
           if (!adapter.tts) throw new Error(`createAI: provider "${spec.provider}" does not support tts`);
-          return adapter.tts({ text: input.text, voiceId, lang: input.lang, format: input.format, rate: input.rate, spec });
+          return adapter.tts({
+            text: input.text,
+            voiceId,
+            lang: input.lang,
+            format: input.format,
+            rate: input.rate,
+            pronunciations: input.pronunciations,
+            spec
+          });
         }
       });
     },