@broberg/ai-sdk 0.37.3 → 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";
@@ -75,6 +87,24 @@ interface Message {
     toolCalls?: ToolCallLike[];
     /** Set on `tool` role messages — which call this result answers. */
     toolCallId?: string;
+    /** F049 — Mistral's `prefix`: start the model's reply with this text instead of
+     *  asking it to. Only valid on the LAST message, and only when that message is an
+     *  `assistant` one; anything else throws rather than being sent, because Mistral
+     *  documents no behaviour for it elsewhere.
+     *
+     *  Mistral's own first-listed use case is Language Adherence, and it pairs with a
+     *  system instruction rather than replacing one — they warn that a prefix alone
+     *  gives "noisy and unpredictable answers". Measured on this repo's own data: an
+     *  explicit language rule in the system prompt already took 5/15 wrong answers to
+     *  0/15, and every leak began in the FIRST words ("Tak for din henvendelse"), which
+     *  is exactly what a prefix pins.
+     *
+     *  **The SDK strips the prefix back off the response**, in `chat` and `chatStream`
+     *  alike, so a caller never has to. Mistral's own example does
+     *  `content[len(prefix):]` by hand; forgetting it puts "Here is the answer in
+     *  Norwegian:" at the top of a real customer's email — a defect that reads as
+     *  formatting rather than as a bug. */
+    prefix?: boolean;
 }
 /** SDK-level tool definition. Adapters convert this to each provider's format
  *  (F4.5). `parameters` is a JSON Schema object. */
@@ -405,6 +435,7 @@ interface PodcastResult {
     mimeType: string;
     usage: Usage;
 }
+
 interface TtsRequest {
     text: string;
     voiceId: string;
@@ -414,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 {
@@ -635,6 +674,10 @@ declare const messageSchema: z.ZodObject<{
         arguments?: Record<string, unknown> | undefined;
     }>, "many">>;
     toolCallId: z.ZodOptional<z.ZodString>;
+    /** F049 — see Message.prefix. Position/role validity is enforced in the adapter,
+     *  not here: the rule is about a message's place in the ARRAY, which a per-message
+     *  schema cannot see. */
+    prefix: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     content: string | ({
         text: string;
@@ -651,6 +694,7 @@ declare const messageSchema: z.ZodObject<{
         args?: Record<string, unknown> | undefined;
         arguments?: Record<string, unknown> | undefined;
     }[] | undefined;
+    prefix?: boolean | undefined;
     toolCallId?: string | undefined;
 }, {
     content: string | ({
@@ -668,6 +712,7 @@ declare const messageSchema: z.ZodObject<{
         args?: Record<string, unknown> | undefined;
         arguments?: Record<string, unknown> | undefined;
     }[] | undefined;
+    prefix?: boolean | undefined;
     toolCallId?: string | undefined;
 }>;
 declare const chatInputSchema: z.ZodObject<{
@@ -760,6 +805,10 @@ declare const chatInputSchema: z.ZodObject<{
             arguments?: Record<string, unknown> | undefined;
         }>, "many">>;
         toolCallId: z.ZodOptional<z.ZodString>;
+        /** F049 — see Message.prefix. Position/role validity is enforced in the adapter,
+         *  not here: the rule is about a message's place in the ARRAY, which a per-message
+         *  schema cannot see. */
+        prefix: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         content: string | ({
             text: string;
@@ -776,6 +825,7 @@ declare const chatInputSchema: z.ZodObject<{
             args?: Record<string, unknown> | undefined;
             arguments?: Record<string, unknown> | undefined;
         }[] | undefined;
+        prefix?: boolean | undefined;
         toolCallId?: string | undefined;
     }, {
         content: string | ({
@@ -793,6 +843,7 @@ declare const chatInputSchema: z.ZodObject<{
             args?: Record<string, unknown> | undefined;
             arguments?: Record<string, unknown> | undefined;
         }[] | undefined;
+        prefix?: boolean | undefined;
         toolCallId?: string | undefined;
     }>, "many">>;
     system: z.ZodOptional<z.ZodString>;
@@ -833,6 +884,7 @@ declare const chatInputSchema: z.ZodObject<{
             args?: Record<string, unknown> | undefined;
             arguments?: Record<string, unknown> | undefined;
         }[] | undefined;
+        prefix?: boolean | undefined;
         toolCallId?: string | undefined;
     }[] | undefined;
     tools?: {
@@ -877,6 +929,7 @@ declare const chatInputSchema: z.ZodObject<{
             args?: Record<string, unknown> | undefined;
             arguments?: Record<string, unknown> | undefined;
         }[] | undefined;
+        prefix?: boolean | undefined;
         toolCallId?: string | undefined;
     }[] | undefined;
     tools?: {
@@ -1775,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.
      *
@@ -1806,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;
@@ -1826,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<{
@@ -2182,6 +2265,11 @@ interface OpenAICompatibleConfig {
     extraHeaders?: Record<string, string>;
     /** Injectable fetch for the streaming path (tests). */
     fetch?: typeof fetch;
+    /** F049 — the provider understands `prefix: true` on a trailing assistant message.
+     *  Mistral only. A prefix sent anywhere else is REFUSED rather than dropped: a
+     *  silently ignored flag means the call succeeds, the language is not pinned, and
+     *  the caller believes it is. */
+    supportsPrefix?: boolean;
     /** OpenRouter ground-truth cost (F010): send `usage:{include:true}` and use the
      *  response's `usage.cost` (USD) as costUsd, falling back to the pricing table.
      *  Only OpenRouter returns this field — openai/deepinfra leave it false. */
@@ -2214,8 +2302,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.37.3";
-declare const SDK_TAG: "@broberg/ai-sdk@0.37.3";
+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

@@ -619,6 +619,7 @@ function autoCacheKey(messages) {
 function toOpenAIMessage(m) {
   if (typeof m.content === "string") {
     const base = { role: m.role, content: m.content };
+    if (m.prefix) base.prefix = true;
     if (m.toolCallId) base.tool_call_id = m.toolCallId;
     if (m.toolCalls && m.toolCalls.length > 0) {
       base.tool_calls = m.toolCalls.map((tc) => ({
@@ -640,7 +641,70 @@ function toOpenAIMessage(m) {
   });
   return { role: m.role, content };
 }
+function makeStreamPrefixStripper(prefix) {
+  if (!prefix) return (d) => d;
+  let seen = "";
+  let done = false;
+  let trimNext = false;
+  return (delta) => {
+    if (done) {
+      if (!trimNext) return delta;
+      const t = delta.trimStart();
+      if (t.length === 0) return "";
+      trimNext = false;
+      return t;
+    }
+    seen += delta;
+    if (seen.length < prefix.length) {
+      if (!prefix.startsWith(seen)) {
+        done = true;
+        return seen;
+      }
+      return "";
+    }
+    done = true;
+    const rest = seen.startsWith(prefix) ? seen.slice(prefix.length) : seen;
+    if (rest.length > 0) return rest.trimStart();
+    trimNext = true;
+    return "";
+  };
+}
+function stripPrefix(text, prefix) {
+  if (!prefix) return text;
+  return text.startsWith(prefix) ? text.slice(prefix.length).trimStart() : text;
+}
+function prefixText(messages) {
+  const last = messages[messages.length - 1];
+  if (!last?.prefix) return void 0;
+  return typeof last.content === "string" ? last.content : void 0;
+}
+function assertPrefixUsage(messages, config) {
+  const at = messages.findIndex((m) => m.prefix === true);
+  if (at === -1) return;
+  if (!config.supportsPrefix) {
+    throw new Error(
+      `${config.name} adapter: message.prefix is not supported by "${config.name}" \u2014 only mistral implements it. Remove the flag, or route this call with override:{provider:"mistral", model:"<a mistral model>"}.`
+    );
+  }
+  if (at !== messages.length - 1) {
+    throw new Error(
+      `${config.name} adapter: message.prefix is only valid on the LAST message (found at index ${at} of ${messages.length}). The provider documents no behaviour for it elsewhere.`
+    );
+  }
+  const last = messages[at];
+  if (last.role !== "assistant") {
+    throw new Error(
+      `${config.name} adapter: message.prefix is only valid on an "assistant" message (found on "${last.role}"). The prefix IS the start of the assistant's reply.`
+    );
+  }
+  if (typeof last.content !== "string") {
+    throw new Error(
+      `${config.name} adapter: a prefix message's content must be a plain string (got content blocks). The prefix is text the reply continues from.`
+    );
+  }
+}
 function buildChatBody(req, config) {
+  assertPrefixUsage(req.messages, config);
   const body = {
     model: req.spec.model,
     messages: req.messages.map(toOpenAIMessage)
@@ -680,7 +744,7 @@ function makeOpenAICompatibleAdapter(config) {
     }
     const data = res.json;
     const msg = data.choices?.[0]?.message;
-    const text = contentToText(msg?.content);
+    const text = stripPrefix(contentToText(msg?.content), prefixText(req.messages));
     const toolCalls = msg?.tool_calls?.map(
       (tc) => fromProviderToolCall(tc, "openai")
     );
@@ -713,6 +777,7 @@ function makeOpenAICompatibleAdapter(config) {
     if (!apiKey) {
       throw new Error(`${config.name} adapter: API key not set (env ${config.name.toUpperCase()}_API_KEY)`);
     }
+    const stripStreamPrefix = makeStreamPrefixStripper(prefixText(req.messages));
     const body = {
       ...buildChatBody(req, config),
       stream: true,
@@ -744,7 +809,8 @@ function makeOpenAICompatibleAdapter(config) {
       if (choice) {
         const delta = choice.delta ?? {};
         if (typeof delta.content === "string" && delta.content.length > 0) {
-          yield { type: "text", delta: delta.content };
+          const out = stripStreamPrefix(delta.content);
+          if (out.length > 0) yield { type: "text", delta: out };
         }
         for (const tc of delta.tool_calls ?? []) {
           const idx = tc.index ?? 0;
@@ -1296,7 +1362,7 @@ var VOXTRAL_PRICE_PER_MIN = {
 };
 function mistralAdapter(config = {}) {
   const baseUrl = config.baseUrl ?? "https://api.mistral.ai/v1";
-  const base = makeOpenAICompatibleAdapter({ name: "mistral", baseUrl, apiKey: config.apiKey, supportsPromptCacheKey: true });
+  const base = makeOpenAICompatibleAdapter({ name: "mistral", baseUrl, apiKey: config.apiKey, supportsPromptCacheKey: true, supportsPrefix: true });
   function key() {
     const k = config.apiKey ?? process.env.MISTRAL_API_KEY;
     if (!k) throw new Error("mistral adapter: API key not set (env MISTRAL_API_KEY)");
@@ -1481,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 = {
@@ -1493,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;
@@ -1536,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(() => "");
@@ -1596,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";
@@ -1644,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>`;
@@ -2812,7 +2933,11 @@ var messageSchema = z.object({
   role: z.enum(["system", "user", "assistant", "tool"]),
   content: z.union([z.string(), z.array(contentPartSchema)]),
   toolCalls: z.array(toolCallSchema).optional(),
-  toolCallId: z.string().optional()
+  toolCallId: z.string().optional(),
+  /** F049 — see Message.prefix. Position/role validity is enforced in the adapter,
+   *  not here: the rule is about a message's place in the ARRAY, which a per-message
+   *  schema cannot see. */
+  prefix: z.boolean().optional()
 });
 var callOptions = {
   tier: tierSchema.optional(),
@@ -2953,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.
    *
@@ -2997,8 +3131,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.37.3";
-var SDK_TAG = "@broberg/ai-sdk@0.37.3";
+var VERSION = "0.39.0";
+var SDK_TAG = "@broberg/ai-sdk@0.39.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {
@@ -3541,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
+          });
         }
       });
     },