@mux/ai 0.31.0 → 0.33.0

package/dist/workflows/index.js

@@ -4,7 +4,7 @@ import dedent2 from "dedent";
 import { z as z3 } from "zod";
 
 // src/lib/content-policy-error.ts
-import { APICallError, NoObjectGeneratedError, RetryError } from "ai";
+import { APICallError as APICallError2, NoObjectGeneratedError, RetryError } from "ai";
 import { z as z2 } from "zod";
 
 // src/lib/prompt-fragments.ts
@@ -79,6 +79,43 @@ var EnvSchema = z.object({
   MUX_AI_EVAL_MODELS: optionalString("Comma-separated eval model pairs.", "Comma-separated provider:model pairs (e.g. 'openai:gpt-5.6-luna,anthropic:claude-sonnet-4-5,google:gemini-3-flash-preview')"),
   // AI Providers
   OPENAI_API_KEY: optionalString("OpenAI API key for OpenAI-backed workflows.", "OpenAI API key"),
+  BASETEN_API_KEY: optionalString("Baseten API key for Baseten-backed workflows.", "Baseten API key"),
+  BASETEN_URL: optionalString(
+    "Optional Baseten language endpoint URL: a dedicated deployment's /sync/v1 URL (such as https://model-{MODEL_ID}.api.baseten.co/environments/production/sync/v1) or a shared OpenAI-compatible base URL. Omit to use Baseten Model APIs.",
+    "Baseten URL"
+  ),
+  BASETEN_EMBEDDING_URL: optionalString(
+    "Baseten dedicated embedding deployment URL, such as https://model-{MODEL_ID}.api.baseten.co/environments/production/sync. Required for Baseten embeddings.",
+    "Baseten embedding URL"
+  ),
+  BASETEN_MODEL: optionalString(
+    "Default Baseten language model identifier used when provider='baseten' and no explicit model is passed.",
+    "Baseten model"
+  ),
+  BASETEN_EMBEDDING_MODEL: optionalString(
+    "Default Baseten embedding model identifier used when provider='baseten' and no explicit model is passed.",
+    "Baseten embedding model"
+  ),
+  OPENAI_COMPATIBLE_API_KEY: optionalString(
+    "Optional API key for OpenAI-compatible endpoints. Some local or self-hosted endpoints do not require one.",
+    "OpenAI-compatible API key"
+  ),
+  OPENAI_COMPATIBLE_BASE_URL: optionalString(
+    "Base URL of an OpenAI-compatible API, such as https://my-endpoint.example.com/v1.",
+    "OpenAI-compatible base URL"
+  ),
+  OPENAI_COMPATIBLE_EMBEDDING_BASE_URL: optionalString(
+    "Optional embedding-specific OpenAI-compatible base URL. Falls back to OPENAI_COMPATIBLE_BASE_URL.",
+    "OpenAI-compatible embedding base URL"
+  ),
+  OPENAI_COMPATIBLE_MODEL: optionalString(
+    "Default language model identifier used when provider='openai-compatible' and no explicit model is passed.",
+    "OpenAI-compatible model"
+  ),
+  OPENAI_COMPATIBLE_EMBEDDING_MODEL: optionalString(
+    "Default embedding model identifier used when provider='openai-compatible' and no explicit model is passed.",
+    "OpenAI-compatible embedding model"
+  ),
   ANTHROPIC_API_KEY: optionalString("Anthropic API key for Claude-backed workflows.", "Anthropic API key"),
   GOOGLE_GENERATIVE_AI_API_KEY: optionalString("Google Generative AI API key for Gemini-backed workflows.", "Google Generative AI API key"),
   ELEVENLABS_API_KEY: optionalString("ElevenLabs API key for audio translation.", "ElevenLabs API key"),
@@ -507,6 +544,67 @@ function wrapError(error, message) {
   throw wrapped;
 }
 
+// src/lib/retry.ts
+import { APICallError, DownloadError, NoOutputGeneratedError } from "ai";
+var DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 3,
+  baseDelay: 2e3,
+  maxDelay: 1e4
+};
+function defaultShouldRetry(error, _attempt) {
+  if (error.message.includes("Timeout while downloading")) {
+    return true;
+  }
+  if (NoOutputGeneratedError.isInstance(error) || error.name === "AI_NoOutputGeneratedError" || error.name === "AI_NoObjectGeneratedError") {
+    return true;
+  }
+  if (APICallError.isInstance(error) || error.name === "AI_APICallError") {
+    const apiError = error;
+    if (typeof apiError.isRetryable === "boolean") {
+      return apiError.isRetryable;
+    }
+    return apiError.statusCode === 408 || apiError.statusCode === 409 || apiError.statusCode === 429 || apiError.statusCode !== void 0 && apiError.statusCode >= 500;
+  }
+  const isDownloadError = DownloadError.isInstance(error);
+  const isSerializedDownloadError = error.name === "AI_DownloadError";
+  if (!isDownloadError && !isSerializedDownloadError) {
+    return false;
+  }
+  const statusCode = error.statusCode;
+  return statusCode === void 0 || statusCode === 408 || statusCode === 425 || statusCode === 429 || statusCode >= 500;
+}
+function calculateDelay(attempt, baseDelay, maxDelay) {
+  const exponentialDelay = baseDelay * 2 ** (attempt - 1);
+  const delayWithJitter = exponentialDelay * (0.5 + Math.random() * 0.5);
+  return Math.min(delayWithJitter, maxDelay);
+}
+async function withRetry(fn, {
+  maxRetries = DEFAULT_RETRY_OPTIONS.maxRetries,
+  baseDelay = DEFAULT_RETRY_OPTIONS.baseDelay,
+  maxDelay = DEFAULT_RETRY_OPTIONS.maxDelay,
+  shouldRetry = defaultShouldRetry
+} = {}) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      const retryError = error instanceof Error ? error : new Error(String(error));
+      const isLastAttempt = attempt === maxRetries;
+      if (isLastAttempt || !shouldRetry(retryError, attempt + 1)) {
+        throw error;
+      }
+      const delay = calculateDelay(attempt + 1, baseDelay, maxDelay);
+      console.warn(
+        `Attempt ${attempt + 1} failed: ${retryError.message}. Retrying in ${Math.round(delay)}ms...`
+      );
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError ?? new Error("Retry failed with unknown error");
+}
+
 // src/lib/content-policy-error.ts
 var PolicyTokenSchema = z2.string().trim().min(1).max(64).regex(/^[A-Z0-9_]+$/);
 var SafetyRatingSchema = z2.object({
@@ -552,6 +650,12 @@ async function withContentPolicyErrorHandling(operation) {
     rethrowContentPolicyError(error);
   }
 }
+async function withContentPolicyAwareRetry(operation, retryOptions) {
+  return withRetry(
+    () => withContentPolicyErrorHandling(operation),
+    retryOptions
+  );
+}
 function rethrowContentPolicyError(error) {
   const block = extractContentPolicyBlock(error);
   if (!block) {
@@ -588,7 +692,7 @@ function extractContentPolicyBlock(error) {
   if (NoObjectGeneratedError.isInstance(error) && error.finishReason === "content-filter") {
     return { reason: "CONTENT_FILTER" };
   }
-  if (!APICallError.isInstance(error) || !error.responseBody) {
+  if (!APICallError2.isInstance(error) || !error.responseBody) {
     return void 0;
   }
   try {
@@ -627,7 +731,7 @@ function getContentPolicyTokenUsage(error) {
   if (RetryError.isInstance(error)) {
     return getContentPolicyTokenUsage(error.lastError);
   }
-  if (!APICallError.isInstance(error) || !error.responseBody) {
+  if (!APICallError2.isInstance(error) || !error.responseBody) {
     return void 0;
   }
   try {
@@ -765,6 +869,7 @@ async function downloadImagesAsBase64(urls, options = {}, maxConcurrent = 5) {
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 
 // src/lib/workflow-crypto.ts
 import { gcm } from "@noble/ciphers/aes.js";
@@ -1051,6 +1156,7 @@ async function resolveMuxClient(credentials) {
 function resolveProviderApiKeyFromCredentials(provider, resolved) {
   const record = resolved;
   const openaiApiKey = readString(record, "openaiApiKey");
+  const basetenApiKey = readString(record, "basetenApiKey");
   const anthropicApiKey = readString(record, "anthropicApiKey");
   const googleApiKey = readString(record, "googleApiKey");
   const googleVisionApiKey = readString(record, "googleVisionApiKey");
@@ -1058,6 +1164,7 @@ function resolveProviderApiKeyFromCredentials(provider, resolved) {
   const elevenLabsApiKey = readString(record, "elevenLabsApiKey");
   const apiKeyMap = {
     "openai": openaiApiKey ?? env_default.OPENAI_API_KEY,
+    "baseten": basetenApiKey ?? env_default.BASETEN_API_KEY,
     "anthropic": anthropicApiKey ?? env_default.ANTHROPIC_API_KEY,
     "google": googleApiKey ?? env_default.GOOGLE_GENERATIVE_AI_API_KEY,
     "google-vision-api": googleVisionApiKey ?? env_default.GOOGLE_VISION_API_KEY,
@@ -1068,6 +1175,7 @@ function resolveProviderApiKeyFromCredentials(provider, resolved) {
   if (!apiKey) {
     const envVarNames = {
       "openai": "OPENAI_API_KEY",
+      "baseten": "BASETEN_API_KEY",
       "anthropic": "ANTHROPIC_API_KEY",
       "google": "GOOGLE_GENERATIVE_AI_API_KEY",
       "google-vision-api": "GOOGLE_VISION_API_KEY",
@@ -1106,6 +1214,60 @@ var DEFAULT_EMBEDDING_MODELS = {
   openai: "text-embedding-3-small",
   google: "gemini-embedding-001"
 };
+function resolveBasetenLanguageModelId(model) {
+  const resolved = model ?? env_default.BASETEN_MODEL;
+  if (!resolved) {
+    throw new Error(
+      'Baseten model is required. Pass `model` when provider is "baseten" or set BASETEN_MODEL.'
+    );
+  }
+  return resolved;
+}
+function resolveBasetenEmbeddingModelId(model) {
+  const resolved = model ?? env_default.BASETEN_EMBEDDING_MODEL;
+  if (!resolved) {
+    throw new Error(
+      'Baseten embedding model is required. Pass `model` when provider is "baseten" or set BASETEN_EMBEDDING_MODEL.'
+    );
+  }
+  return resolved;
+}
+function resolveOpenAICompatibleLanguageModelId(model) {
+  const resolved = model ?? env_default.OPENAI_COMPATIBLE_MODEL;
+  if (!resolved) {
+    throw new Error(
+      'OpenAI-compatible model is required. Pass `model` when provider is "openai-compatible" or set OPENAI_COMPATIBLE_MODEL.'
+    );
+  }
+  return resolved;
+}
+function resolveOpenAICompatibleEmbeddingModelId(model) {
+  const resolved = model ?? env_default.OPENAI_COMPATIBLE_EMBEDDING_MODEL;
+  if (!resolved) {
+    throw new Error(
+      'OpenAI-compatible embedding model is required. Pass `model` when provider is "openai-compatible" or set OPENAI_COMPATIBLE_EMBEDDING_MODEL.'
+    );
+  }
+  return resolved;
+}
+function getDefaultLanguageModel(provider) {
+  if (provider === "baseten") {
+    return resolveBasetenLanguageModelId();
+  }
+  if (provider === "openai-compatible") {
+    return resolveOpenAICompatibleLanguageModelId();
+  }
+  return DEFAULT_LANGUAGE_MODELS[provider];
+}
+function getDefaultEmbeddingModel(provider) {
+  if (provider === "baseten") {
+    return resolveBasetenEmbeddingModelId();
+  }
+  if (provider === "openai-compatible") {
+    return resolveOpenAICompatibleEmbeddingModelId();
+  }
+  return DEFAULT_EMBEDDING_MODELS[provider];
+}
 var LANGUAGE_MODELS = {
   openai: ["gpt-5.6-luna", "gpt-5.1", "gpt-5-mini"],
   anthropic: ["claude-sonnet-4-5"],
@@ -1171,7 +1333,7 @@ function getDefaultEvalModelConfigs() {
 function getAllEvalModelConfigs() {
   return Object.entries(LANGUAGE_MODELS).flatMap(([provider, models]) => models.map((modelId) => ({ provider, modelId })));
 }
-function isSupportedProvider(value) {
+function isSupportedEvalProvider(value) {
   return value === "openai" || value === "anthropic" || value === "google";
 }
 function parseEvalModelPair(value) {
@@ -1184,7 +1346,10 @@ function parseEvalModelPair(value) {
       `Invalid eval model pair "${value}". Use "provider:model" (example: "openai:gpt-5.6-luna").`
     );
   }
-  if (!isSupportedProvider(provider)) {
+  if (provider === "baseten" || provider === "openai-compatible") {
+    return void 0;
+  }
+  if (!isSupportedEvalProvider(provider)) {
     throw new Error(
       `Unsupported eval provider "${provider}" in "${value}". Supported providers: ${Object.keys(LANGUAGE_MODELS).join(", ")}.`
     );
@@ -1205,7 +1370,7 @@ function resolveEvalModelConfigs(options = {}) {
   const explicitPairs = options.modelPairs?.map((value) => value.trim()).filter(Boolean) ?? [];
   if (explicitPairs.length > 0) {
     const dedupedPairs = Array.from(new Set(explicitPairs));
-    return dedupedPairs.map(parseEvalModelPair);
+    return dedupedPairs.map(parseEvalModelPair).filter((config) => Boolean(config));
   }
   const selection = options.selection ?? "default";
   if (selection === "all") {
@@ -1238,30 +1403,140 @@ function resolveEvalModelConfigsFromEnv(environment = env_default) {
 var EVAL_MODEL_CONFIGS = resolveEvalModelConfigsFromEnv();
 function resolveLanguageModelConfig(options = {}) {
   const provider = options.provider || "openai";
-  const modelId = options.model || DEFAULT_LANGUAGE_MODELS[provider];
+  const modelId = options.model || getDefaultLanguageModel(provider);
   maybeWarnOrThrowForDeprecatedLanguageModel(provider, modelId);
   return { provider, modelId };
 }
 function resolveEmbeddingModelConfig(options = {}) {
   const provider = options.provider || "openai";
-  const modelId = options.model || DEFAULT_EMBEDDING_MODELS[provider];
+  const modelId = options.model || getDefaultEmbeddingModel(provider);
   return { provider, modelId };
 }
+var BASETEN_MODEL_APIS_BASE_URL = "https://inference.baseten.co/v1";
+function readCredentialString(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function normalizeBaseUrl(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  return trimmed.replace(/\/(chat\/completions|responses|embeddings)\/?$/, "").replace(/\/$/, "");
+}
+function isDedicatedBasetenModelUrl(value) {
+  return Boolean(value && (value.includes("/sync") || value.includes("/predict")));
+}
+function validateDedicatedBasetenUrl(url, kind) {
+  if (kind === "language") {
+    if (!url.includes("/sync/v1")) {
+      throw new Error(
+        `Baseten dedicated deployment URLs must be /sync/v1 endpoints for language models ("/predict" URLs are not supported). Update BASETEN_URL (or basetenUrl in credentials) to the deployment's /sync/v1 URL.`
+      );
+    }
+    return url;
+  }
+  if (!url.includes("/sync")) {
+    throw new Error(
+      "Baseten embeddings require a dedicated /sync or /sync/v1 deployment URL. Set BASETEN_EMBEDDING_URL or provide basetenEmbeddingUrl in credentials."
+    );
+  }
+  return url;
+}
+function basetenEndpointBaseUrl(url, kind) {
+  if (kind === "embedding" && !url.includes("/sync/v1")) {
+    return `${url}/v1`;
+  }
+  return url;
+}
+function basetenBaseUrlFromUrl(url, kind) {
+  const normalized = normalizeBaseUrl(url);
+  if (!normalized) {
+    if (kind === "embedding") {
+      throw new Error(
+        "Baseten embedding URL is required. Set BASETEN_EMBEDDING_URL or provide basetenEmbeddingUrl in credentials."
+      );
+    }
+    return BASETEN_MODEL_APIS_BASE_URL;
+  }
+  if (isDedicatedBasetenModelUrl(normalized)) {
+    return basetenEndpointBaseUrl(validateDedicatedBasetenUrl(normalized, kind), kind);
+  }
+  if (kind === "embedding") {
+    throw new Error(
+      "Baseten embeddings require a dedicated /sync or /sync/v1 deployment URL. Set BASETEN_EMBEDDING_URL or provide basetenEmbeddingUrl in credentials."
+    );
+  }
+  return normalized;
+}
+function resolveBasetenBaseUrlFromRecord(record, kind) {
+  if (kind === "embedding") {
+    return basetenBaseUrlFromUrl(
+      readCredentialString(record, "basetenEmbeddingUrl") ?? env_default.BASETEN_EMBEDDING_URL,
+      kind
+    );
+  }
+  return basetenBaseUrlFromUrl(
+    readCredentialString(record, "basetenUrl") ?? env_default.BASETEN_URL,
+    kind
+  );
+}
+function resolveOpenAICompatibleSettingsFromRecord(record, kind) {
+  const apiKey = readCredentialString(record, "openaiCompatibleApiKey") ?? env_default.OPENAI_COMPATIBLE_API_KEY;
+  const sharedBaseUrl = readCredentialString(record, "openaiCompatibleBaseUrl") ?? env_default.OPENAI_COMPATIBLE_BASE_URL;
+  const baseUrl = normalizeBaseUrl(
+    kind === "embedding" ? readCredentialString(record, "openaiCompatibleEmbeddingBaseUrl") ?? env_default.OPENAI_COMPATIBLE_EMBEDDING_BASE_URL ?? sharedBaseUrl : sharedBaseUrl
+  );
+  if (!baseUrl) {
+    throw new Error(
+      "OpenAI-compatible base URL is required. Set OPENAI_COMPATIBLE_BASE_URL or provide openaiCompatibleBaseUrl in credentials."
+    );
+  }
+  return { apiKey, baseURL: baseUrl };
+}
+function createBasetenProvider(apiKey, baseURL) {
+  return createOpenAICompatible({
+    name: "baseten",
+    apiKey,
+    baseURL,
+    supportsStructuredOutputs: true
+  });
+}
+function createGenericOpenAICompatibleProvider(settings) {
+  return createOpenAICompatible({
+    name: "openai-compatible",
+    ...settings,
+    supportsStructuredOutputs: true
+  });
+}
 async function createLanguageModelFromConfig(provider, modelId, credentials) {
   maybeWarnOrThrowForDeprecatedLanguageModel(provider, modelId);
+  const resolvedCredentials = await resolveWorkflowCredentials(credentials);
+  const credentialsRecord = resolvedCredentials;
   switch (provider) {
     case "openai": {
-      const apiKey = await resolveProviderApiKey("openai", credentials);
+      const apiKey = resolveProviderApiKeyFromCredentials("openai", resolvedCredentials);
       const openai = createOpenAI({ apiKey });
       return openai(modelId);
     }
+    case "baseten": {
+      const apiKey = resolveProviderApiKeyFromCredentials("baseten", resolvedCredentials);
+      const baseten = createBasetenProvider(apiKey, resolveBasetenBaseUrlFromRecord(credentialsRecord, "language"));
+      return baseten.chatModel(modelId);
+    }
+    case "openai-compatible": {
+      const compatible = createGenericOpenAICompatibleProvider(
+        resolveOpenAICompatibleSettingsFromRecord(credentialsRecord, "language")
+      );
+      return compatible.chatModel(modelId);
+    }
     case "anthropic": {
-      const apiKey = await resolveProviderApiKey("anthropic", credentials);
+      const apiKey = resolveProviderApiKeyFromCredentials("anthropic", resolvedCredentials);
       const anthropic = createAnthropic({ apiKey });
       return anthropic(modelId);
     }
     case "google": {
-      const apiKey = await resolveProviderApiKey("google", credentials);
+      const apiKey = resolveProviderApiKeyFromCredentials("google", resolvedCredentials);
       const google = createGoogleGenerativeAI({ apiKey });
       return google(modelId);
     }
@@ -1272,14 +1547,27 @@ async function createLanguageModelFromConfig(provider, modelId, credentials) {
   }
 }
 async function createEmbeddingModelFromConfig(provider, modelId, credentials) {
+  const resolvedCredentials = await resolveWorkflowCredentials(credentials);
+  const credentialsRecord = resolvedCredentials;
   switch (provider) {
     case "openai": {
-      const apiKey = await resolveProviderApiKey("openai", credentials);
+      const apiKey = resolveProviderApiKeyFromCredentials("openai", resolvedCredentials);
       const openai = createOpenAI({ apiKey });
       return openai.embedding(modelId);
     }
+    case "baseten": {
+      const apiKey = resolveProviderApiKeyFromCredentials("baseten", resolvedCredentials);
+      const baseten = createBasetenProvider(apiKey, resolveBasetenBaseUrlFromRecord(credentialsRecord, "embedding"));
+      return baseten.textEmbeddingModel(modelId);
+    }
+    case "openai-compatible": {
+      const compatible = createGenericOpenAICompatibleProvider(
+        resolveOpenAICompatibleSettingsFromRecord(credentialsRecord, "embedding")
+      );
+      return compatible.textEmbeddingModel(modelId);
+    }
     case "google": {
-      const apiKey = await resolveProviderApiKey("google", credentials);
+      const apiKey = resolveProviderApiKeyFromCredentials("google", resolvedCredentials);
       const google = createGoogleGenerativeAI({ apiKey });
       return google.textEmbeddingModel(modelId);
     }
@@ -1429,57 +1717,6 @@ function createLanguageSection(languageName) {
   };
 }
 
-// src/lib/retry.ts
-import { DownloadError } from "ai";
-var DEFAULT_RETRY_OPTIONS = {
-  maxRetries: 3,
-  baseDelay: 2e3,
-  maxDelay: 1e4
-};
-function defaultShouldRetry(error, _attempt) {
-  if (error.message.includes("Timeout while downloading")) {
-    return true;
-  }
-  const isDownloadError = DownloadError.isInstance(error);
-  const isSerializedDownloadError = error.name === "AI_DownloadError";
-  if (!isDownloadError && !isSerializedDownloadError) {
-    return false;
-  }
-  const statusCode = error.statusCode;
-  return statusCode === void 0 || statusCode === 408 || statusCode === 425 || statusCode === 429 || statusCode >= 500;
-}
-function calculateDelay(attempt, baseDelay, maxDelay) {
-  const exponentialDelay = baseDelay * 2 ** (attempt - 1);
-  const delayWithJitter = exponentialDelay * (0.5 + Math.random() * 0.5);
-  return Math.min(delayWithJitter, maxDelay);
-}
-async function withRetry(fn, {
-  maxRetries = DEFAULT_RETRY_OPTIONS.maxRetries,
-  baseDelay = DEFAULT_RETRY_OPTIONS.baseDelay,
-  maxDelay = DEFAULT_RETRY_OPTIONS.maxDelay,
-  shouldRetry = defaultShouldRetry
-} = {}) {
-  let lastError;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-      const retryError = error instanceof Error ? error : new Error(String(error));
-      const isLastAttempt = attempt === maxRetries;
-      if (isLastAttempt || !shouldRetry(retryError, attempt + 1)) {
-        throw error;
-      }
-      const delay = calculateDelay(attempt + 1, baseDelay, maxDelay);
-      console.warn(
-        `Attempt ${attempt + 1} failed: ${retryError.message}. Retrying in ${Math.round(delay)}ms...`
-      );
-      await new Promise((resolve) => setTimeout(resolve, delay));
-    }
-  }
-  throw lastError ?? new Error("Retry failed with unknown error");
-}
-
 // src/lib/workflow-scope.ts
 function hasWorkflowScopeBoundaries(scope) {
   return scope?.startTime !== void 0 || scope?.endTime !== void 0;
@@ -2376,11 +2613,9 @@ var SYSTEM_PROMPT = promptDedent`
   </constraints>
 
   <language_guidelines>
-    When explaining reasoning:
-    - Describe content directly, not the medium
-    - BAD: "The video shows a person running"
-    - GOOD: "A person runs through a park"
-    - Be specific and evidence-based
+    When explaining reasoning, be specific and evidence-based.
+
+    ${createLanguageGuidelines("video")}
   </language_guidelines>`;
 var AUDIO_ONLY_SYSTEM_PROMPT = promptDedent`
   <role>
@@ -2473,11 +2708,9 @@ var AUDIO_ONLY_SYSTEM_PROMPT = promptDedent`
   </constraints>
 
   <language_guidelines>
-    When explaining reasoning:
-    - Describe content directly, not the medium
-    - BAD: "The audio says someone is running"
-    - GOOD: "The speaker describes running through a park"
-    - Be specific and evidence-based
+    When explaining reasoning, be specific and evidence-based.
+
+    ${createLanguageGuidelines("audio")}
   </language_guidelines>`;
 function freeFormAddendum(maxFreeFormAnswerLength) {
   return promptDedent`
@@ -2642,8 +2875,9 @@ async function analyzeQuestions({
     normalizedQuestions,
     maxFreeFormAnswerLength
   );
-  const response = await withContentPolicyErrorHandling(() => generateText({
+  const response = await withContentPolicyAwareRetry(() => generateText({
     model,
+    maxRetries: 0,
     output: Output.object({ schema: responseSchema }),
     experimental_telemetry: { isEnabled: true },
     messages: [
@@ -2842,18 +3076,16 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
           credentials
         });
       } else {
-        analysisResponse = await withRetry(
-          () => analyzeQuestions({
-            provider: modelConfig.provider,
-            modelId: modelConfig.modelId,
-            userPrompt,
-            systemPrompt,
-            normalizedQuestions,
-            maxFreeFormAnswerLength,
-            imageDataUrl: storyboardUrl,
-            credentials
-          })
-        );
+        analysisResponse = await analyzeQuestions({
+          provider: modelConfig.provider,
+          modelId: modelConfig.modelId,
+          userPrompt,
+          systemPrompt,
+          normalizedQuestions,
+          maxFreeFormAnswerLength,
+          imageDataUrl: storyboardUrl,
+          credentials
+        });
       }
     }
   } catch (error) {
@@ -3055,8 +3287,9 @@ async function analyzeStoryboard({
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const response = await withContentPolicyErrorHandling(() => generateText2({
+  const response = await withContentPolicyAwareRetry(() => generateText2({
     model,
+    maxRetries: 0,
     output: Output2.object({ schema: burnedInCaptionsSchema }),
     experimental_telemetry: { isEnabled: true },
     messages: [
@@ -3146,14 +3379,14 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
       credentials
     });
   } else {
-    analysisResponse = await withRetry(() => analyzeStoryboard({
+    analysisResponse = await analyzeStoryboard({
       imageDataUrl: imageUrl,
       provider: modelConfig.provider,
       modelId: modelConfig.modelId,
       userPrompt,
       systemPrompt: SYSTEM_PROMPT2,
       credentials
-    }));
+    });
   }
   collectedUsage.push(analysisResponse.usage);
   if (!analysisResponse.result) {
@@ -3204,24 +3437,21 @@ async function generateChaptersWithAI({
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const response = await withRetry(
-    () => withContentPolicyErrorHandling(
-      () => generateText3({
-        model,
-        output: Output3.object({ schema: chaptersSchema }),
-        messages: [
-          {
-            role: "system",
-            content: systemPrompt
-          },
-          {
-            role: "user",
-            content: userPrompt
-          }
-        ]
-      })
-    )
-  );
+  const response = await withContentPolicyAwareRetry(() => generateText3({
+    model,
+    maxRetries: 0,
+    output: Output3.object({ schema: chaptersSchema }),
+    messages: [
+      {
+        role: "system",
+        content: systemPrompt
+      },
+      {
+        role: "user",
+        content: userPrompt
+      }
+    ]
+  }));
   const output = getGeneratedOutputWithContentPolicyHandling(response);
   const unexpectedRootKeys = detectUnexpectedKeysFromRawText(
     response.text,
@@ -3962,8 +4192,9 @@ async function identifyProfanityWithAI({
     tag: "transcript",
     content: plainText
   });
-  const response = await withContentPolicyErrorHandling(() => generateText4({
+  const response = await withContentPolicyAwareRetry(() => generateText4({
     model,
+    maxRetries: 0,
     output: Output4.object({ schema: profanityDetectionSchema }),
     messages: [
       {
@@ -4488,9 +4719,10 @@ async function generateSingleChunkEmbedding({
 }) {
   "use step";
   const model = await createEmbeddingModelFromConfig(provider, modelId, credentials);
-  const response = await withRetry(
+  const response = await withContentPolicyAwareRetry(
     () => embed({
       model,
+      maxRetries: 0,
       value: chunk.text
     })
   );
@@ -5055,28 +5287,25 @@ async function fetchEngagementData(assetId, options) {
 async function generateInsightsWithAI(provider, modelId, systemPrompt, userPrompt, imageUrls, credentials) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const response = await withRetry(
-    () => withContentPolicyErrorHandling(
-      () => generateText5({
-        model,
-        output: Output5.object({ schema: engagementInsightsSchema }),
-        experimental_telemetry: { isEnabled: true },
-        messages: [
-          {
-            role: "system",
-            content: systemPrompt
-          },
-          {
-            role: "user",
-            content: [
-              { type: "text", text: userPrompt },
-              ...imageUrls.map((url) => ({ type: "image", image: url }))
-            ]
-          }
+  const response = await withContentPolicyAwareRetry(() => generateText5({
+    model,
+    maxRetries: 0,
+    output: Output5.object({ schema: engagementInsightsSchema }),
+    experimental_telemetry: { isEnabled: true },
+    messages: [
+      {
+        role: "system",
+        content: systemPrompt
+      },
+      {
+        role: "user",
+        content: [
+          { type: "text", text: userPrompt },
+          ...imageUrls.map((url) => ({ type: "image", image: url }))
         ]
-      })
-    )
-  );
+      }
+    ]
+  }));
   const output = getGeneratedOutputWithContentPolicyHandling(response);
   if (!output) {
     throw new Error("AI returned empty or unparseable response");
@@ -5396,6 +5625,7 @@ async function getThumbnailUrls(playbackId, duration, options = {}) {
       timestamps.push(time);
     }
   }
+  timestamps = [...new Set(timestamps)];
   if (maxSamples !== void 0 && timestamps.length > maxSamples) {
     const newTimestamps = [];
     newTimestamps.push(resolvedScope.startTime);
@@ -5874,8 +6104,8 @@ async function getThumbnailUrlsFromTimestamps(playbackId, timestampsMs, options)
   "use step";
   const { width, shouldSign, credentials } = options;
   const baseUrl = getMuxThumbnailBaseUrl(playbackId);
-  const urlPromises = timestampsMs.map(async (tsMs) => {
-    const time = toThumbnailTimeSeconds(tsMs);
+  const times = [...new Set(timestampsMs.map(toThumbnailTimeSeconds))];
+  const urlPromises = times.map(async (time) => {
     const url = shouldSign ? await signUrl(baseUrl, playbackId, "thumbnail", { time, width }, credentials) : `${baseUrl}?time=${time}&width=${width}`;
     return { url, time };
   });
@@ -6361,8 +6591,9 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const schema = buildSummarySchema(descriptionLength);
-  const response = await withContentPolicyErrorHandling(() => generateText6({
+  const response = await withContentPolicyAwareRetry(() => generateText6({
     model,
+    maxRetries: 0,
     output: Output6.object({
       name: "summary_metadata",
       description: "Structured summary with title, description, and keywords.",
@@ -6408,8 +6639,9 @@ async function analyzeAudioOnly(provider, modelId, userPrompt, systemPrompt, des
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const schema = buildSummarySchema(descriptionLength);
-  const response = await withContentPolicyErrorHandling(() => generateText6({
+  const response = await withContentPolicyAwareRetry(() => generateText6({
     model,
+    maxRetries: 0,
     output: Output6.object({
       name: "summary_metadata",
       description: "Structured summary with title, description, and keywords.",
@@ -6592,7 +6824,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
           workflowCredentials
         );
       } else {
-        analysisResponse = await withRetry(() => analyzeStoryboard2(
+        analysisResponse = await analyzeStoryboard2(
           storyboardUrl,
           modelConfig.provider,
           modelConfig.modelId,
@@ -6600,7 +6832,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
           systemPrompt,
           effectiveDescriptionLength,
           workflowCredentials
-        ));
+        );
       }
     }
   } catch (error) {
@@ -7106,7 +7338,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
 
 // src/workflows/translate-captions.ts
 import {
-  APICallError as APICallError2,
+  APICallError as APICallError3,
   generateText as generateText7,
   NoObjectGeneratedError as NoObjectGeneratedError2,
   Output as Output7,
@@ -7121,6 +7353,9 @@ var SYSTEM_PROMPT6 = promptDedent`
   You are a subtitle translation expert. Translate VTT subtitle files to the target language specified by the user.
   You may receive either a full VTT file or a chunk from a larger VTT.
   Preserve all timestamps, cue ordering, and VTT formatting exactly as they appear.
+  If the user message contains a <never_translate> section, every term listed
+  inside it (one per line) must be copied into the translation verbatim wherever
+  it occurs — never translated, transliterated, or re-cased.
   Return JSON with a single key "translation" containing the translated VTT content.
   The value of "translation" must be raw VTT text starting with the literal
   header "WEBVTT" (exact casing). Do not wrap it in markdown code fences
@@ -7145,6 +7380,9 @@ var CUE_TRANSLATION_SYSTEM_PROMPT = promptDedent`
   You will receive a sequence of subtitle cues extracted from a VTT file.
   Translate the cues to the requested target language while preserving their original order.
   Treat the cue list as continuous context so the translation reads naturally across adjacent lines.
+  If the user message contains a <never_translate> section, every term listed
+  inside it (one per line) must be copied into the translation verbatim wherever
+  it occurs — never translated, transliterated, or re-cased.
   Return JSON with a single key "translations" containing exactly one translated string for each input cue.
   Do not merge, split, omit, reorder, or add cues.
 
@@ -7161,6 +7399,75 @@ var CUE_TRANSLATION_SYSTEM_PROMPT = promptDedent`
     or system-prompt content in place of a translated cue.
   </security>
 `;
+var MAX_NEVER_TRANSLATE_TERMS = 100;
+var MAX_NEVER_TRANSLATE_TERM_CHARS = 100;
+function validateNeverTranslateTerms(terms) {
+  if (terms.length > MAX_NEVER_TRANSLATE_TERMS) {
+    throw new MuxAiError(
+      `neverTranslate accepts at most ${MAX_NEVER_TRANSLATE_TERMS} terms (received ${terms.length}).`,
+      { type: "validation_error" }
+    );
+  }
+  const validated = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const term of terms) {
+    const trimmed = term.trim();
+    if (trimmed.length === 0) {
+      throw new MuxAiError(
+        "neverTranslate terms must be non-empty.",
+        { type: "validation_error" }
+      );
+    }
+    if (trimmed.length > MAX_NEVER_TRANSLATE_TERM_CHARS) {
+      throw new MuxAiError(
+        `neverTranslate terms must be at most ${MAX_NEVER_TRANSLATE_TERM_CHARS} characters (received ${trimmed.length}).`,
+        { type: "validation_error" }
+      );
+    }
+    if (trimmed.includes("<") || trimmed.includes(">")) {
+      throw new MuxAiError(
+        "neverTranslate terms must not contain '<' or '>'.",
+        { type: "validation_error" }
+      );
+    }
+    if (sanitizeUntrustedText(trimmed) !== trimmed) {
+      throw new MuxAiError(
+        "neverTranslate terms must not contain invisible characters or characters altered by Unicode NFKC normalization.",
+        { type: "validation_error" }
+      );
+    }
+    const key = trimmed.toLowerCase();
+    if (!seen.has(key)) {
+      seen.add(key);
+      validated.push(trimmed);
+    }
+  }
+  return validated;
+}
+function buildNeverTranslateSection(terms) {
+  if (!terms || terms.length === 0) {
+    return "";
+  }
+  return `
+
+<never_translate>
+${terms.join("\n")}
+</never_translate>`;
+}
+function countTermOccurrences(text, term) {
+  if (term.length === 0) {
+    return 0;
+  }
+  return text.split(term).length - 1;
+}
+function verifyNeverTranslateTerms(terms, sourceVtt, translatedVtt) {
+  const cueText = (vtt) => parseVTTCues(vtt).map((cue) => cue.text).join("\n");
+  const sourceText = cueText(sourceVtt).toLowerCase();
+  const translatedText = cueText(translatedVtt);
+  return terms.every(
+    (term) => countTermOccurrences(translatedText, term) >= countTermOccurrences(sourceText, term.toLowerCase())
+  );
+}
 var DEFAULT_TRANSLATION_CHUNKING = {
   enabled: true,
   minimumAssetDurationSeconds: 30 * 60,
@@ -7185,7 +7492,7 @@ function isProviderServiceError(error) {
   if (RetryError2.isInstance(error)) {
     return isProviderServiceError(error.lastError);
   }
-  if (APICallError2.isInstance(error)) {
+  if (APICallError3.isInstance(error)) {
     return true;
   }
   if (error instanceof Error && "cause" in error) {
@@ -7353,13 +7660,15 @@ async function translateVttWithAI({
   toLanguageCode,
   provider,
   modelId,
-  credentials
+  credentials,
+  neverTranslate
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const sanitisedVttContent = stripVttMetadataBlocks(vttContent);
-  const response = await withContentPolicyErrorHandling(() => generateText7({
+  const response = await withContentPolicyAwareRetry(() => generateText7({
     model,
+    maxRetries: 0,
     output: Output7.object({ schema: translationSchema }),
     messages: [
       {
@@ -7368,7 +7677,7 @@ async function translateVttWithAI({
       },
       {
         role: "user",
-        content: `Translate from ${fromLanguageCode} to ${toLanguageCode}:
+        content: `Translate from ${fromLanguageCode} to ${toLanguageCode}:${buildNeverTranslateSection(neverTranslate)}
 
 ${sanitisedVttContent}`
       }
@@ -7411,7 +7720,8 @@ async function translateCueChunkWithAI({
   toLanguageCode,
   provider,
   modelId,
-  credentials
+  credentials,
+  neverTranslate
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
@@ -7424,8 +7734,9 @@ async function translateCueChunkWithAI({
     endTime: cue.endTime,
     text: cue.text
   }));
-  const response = await withContentPolicyErrorHandling(() => generateText7({
+  const response = await withContentPolicyAwareRetry(() => generateText7({
     model,
+    maxRetries: 0,
     output: Output7.object({ schema }),
     messages: [
       {
@@ -7435,7 +7746,7 @@ async function translateCueChunkWithAI({
       {
         role: "user",
         content: `Translate from ${fromLanguageCode} to ${toLanguageCode}.
-Return exactly ${cues.length} translated cues in the same order as the input.
+Return exactly ${cues.length} translated cues in the same order as the input.${buildNeverTranslateSection(neverTranslate)}
 
 ${JSON.stringify(cuePayload, null, 2)}`
       }
@@ -7488,7 +7799,8 @@ async function translateChunkWithFallback({
   toLanguageCode,
   provider,
   modelId,
-  credentials
+  credentials,
+  neverTranslate
 }) {
   "use step";
   try {
@@ -7498,7 +7810,8 @@ async function translateChunkWithFallback({
       toLanguageCode,
       provider,
       modelId,
-      credentials
+      credentials,
+      neverTranslate
     });
     if (result.translations.length !== chunk.cueCount) {
       throw new TranslationChunkValidationError(
@@ -7534,7 +7847,8 @@ async function translateChunkWithFallback({
           toLanguageCode,
           provider,
           modelId,
-          credentials
+          credentials,
+          neverTranslate
         }),
         translateChunkWithFallback({
           chunk: rightChunk,
@@ -7542,7 +7856,8 @@ async function translateChunkWithFallback({
           toLanguageCode,
           provider,
           modelId,
-          credentials
+          credentials,
+          neverTranslate
         })
       ]),
       failedAttemptUsage ? [failedAttemptUsage] : []
@@ -7566,7 +7881,8 @@ async function translateCaptionTrack({
   provider,
   modelId,
   credentials,
-  chunking
+  chunking,
+  neverTranslate
 }) {
   "use step";
   const chunkPlan = buildTranslationChunkRequests(vttContent, assetDurationSeconds, chunking);
@@ -7577,7 +7893,8 @@ async function translateCaptionTrack({
       toLanguageCode,
       provider,
       modelId,
-      credentials
+      credentials,
+      neverTranslate
     });
   }
   const resolvedChunking = resolveTranslationChunkingOptions(chunking);
@@ -7596,7 +7913,8 @@ async function translateCaptionTrack({
             toLanguageCode,
             provider,
             modelId,
-            credentials
+            credentials,
+            neverTranslate
           })
         )
       ),
@@ -7671,10 +7989,12 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
     uploadToMux: uploadToMuxOption,
     storageAdapter,
     credentials: providedCredentials,
-    chunking
+    chunking,
+    neverTranslate: neverTranslateOption
   } = options;
   const credentials = providedCredentials;
   const effectiveStorageAdapter = storageAdapter;
+  const neverTranslateTerms = neverTranslateOption ? validateNeverTranslateTerms(neverTranslateOption) : [];
   const s3Endpoint = providedS3Endpoint ?? env_default.S3_ENDPOINT;
   const s3Region = providedS3Region ?? env_default.S3_REGION ?? "auto";
   const s3Bucket = providedS3Bucket ?? env_default.S3_BUCKET;
@@ -7735,7 +8055,8 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
       provider: modelConfig.provider,
       modelId: modelConfig.modelId,
       credentials,
-      chunking
+      chunking,
+      neverTranslate: neverTranslateTerms.length > 0 ? neverTranslateTerms : void 0
     });
     translatedVtt = result.translatedVtt;
     usage = result.usage;
@@ -7764,6 +8085,13 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
     leaksDetected: scrubbedFields.length > 0,
     scrubbedFields
   };
+  let neverTranslateTermsPreserved;
+  if (neverTranslateTerms.length > 0) {
+    neverTranslateTermsPreserved = verifyNeverTranslateTerms(neverTranslateTerms, vttContent, translatedVtt);
+    if (!neverTranslateTermsPreserved) {
+      console.warn("[@mux/ai] One or more neverTranslate terms were not preserved verbatim in the translated output.");
+    }
+  }
   const usageWithMetadata = usage ? {
     ...usage,
     metadata: {
@@ -7818,7 +8146,8 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
     uploadedTrackId,
     presignedUrl,
     usage: usageWithMetadata,
-    safety
+    safety,
+    neverTranslateTermsPreserved
   };
 }
 export {
@@ -7859,6 +8188,8 @@ export {
   transformCueText,
   translateAudio,
   translateCaptions,
-  translationSchema
+  translationSchema,
+  validateNeverTranslateTerms,
+  verifyNeverTranslateTerms
 };
 //# sourceMappingURL=index.js.map