@mux/ai 0.11.0 → 0.12.0

package/dist/{index-BapL6paa.d.ts → index-DyzifniY.d.ts}

@@ -43,12 +43,14 @@ interface Question {
 interface QuestionAnswer {
     /** The original question */
     question: string;
-    /** Answer selected from the allowed options */
-    answer: string;
-    /** Confidence score between 0 and 1 */
+    /** Answer selected from the allowed options. Undefined when skipped. */
+    answer?: string;
+    /** Confidence score between 0 and 1. Always 0 when skipped. */
     confidence: number;
-    /** Reasoning explaining the answer based on observable evidence */
+    /** Reasoning explaining the answer, or why the question was skipped */
     reasoning: string;
+    /** Whether the question was skipped due to irrelevance to the video content */
+    skipped: boolean;
 }
 /** Configuration options for askQuestions workflow. */
 interface AskQuestionsOptions extends MuxAIOptions {
@@ -82,22 +84,25 @@ interface AskQuestionsResult {
     /** Raw transcript text used for analysis (when includeTranscript is true). */
     transcriptText?: string;
 }
-/** Zod schema for a single answer. */
+/** Zod schema for a single answer (matches the public QuestionAnswer interface). */
 declare const questionAnswerSchema: z.ZodObject<{
     question: z.ZodString;
-    answer: z.ZodString;
+    answer: z.ZodOptional<z.ZodString>;
     confidence: z.ZodNumber;
     reasoning: z.ZodString;
+    skipped: z.ZodBoolean;
 }, "strip", z.ZodTypeAny, {
     question: string;
-    answer: string;
     confidence: number;
     reasoning: string;
+    skipped: boolean;
+    answer?: string | undefined;
 }, {
     question: string;
-    answer: string;
     confidence: number;
     reasoning: string;
+    skipped: boolean;
+    answer?: string | undefined;
 }>;
 type QuestionAnswerType = z.infer<typeof questionAnswerSchema>;
 declare function createAskQuestionsSchema(allowedAnswers: [string, ...string[]]): z.ZodObject<{
@@ -105,18 +110,21 @@ declare function createAskQuestionsSchema(allowedAnswers: [string, ...string[]])
         question: z.ZodString;
         confidence: z.ZodNumber;
         reasoning: z.ZodString;
+        skipped: z.ZodBoolean;
     } & {
-        answer: z.ZodEnum<[string, ...string[]]>;
+        answer: z.ZodEnum<[string, ...string[], "__SKIPPED__"]>;
     }, "strip", z.ZodTypeAny, {
         question: string;
         answer: string;
         confidence: number;
         reasoning: string;
+        skipped: boolean;
     }, {
         question: string;
         answer: string;
         confidence: number;
         reasoning: string;
+        skipped: boolean;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     answers: {
@@ -124,6 +132,7 @@ declare function createAskQuestionsSchema(allowedAnswers: [string, ...string[]])
         answer: string;
         confidence: number;
         reasoning: string;
+        skipped: boolean;
     }[];
 }, {
     answers: {
@@ -131,6 +140,7 @@ declare function createAskQuestionsSchema(allowedAnswers: [string, ...string[]])
         answer: string;
         confidence: number;
         reasoning: string;
+        skipped: boolean;
     }[];
 }>;
 type AskQuestionsSchema = ReturnType<typeof createAskQuestionsSchema>;
@@ -646,9 +656,9 @@ interface SummarizationOptions extends MuxAIOptions {
      * Useful for customizing the AI's output for specific use cases (SEO, social media, etc.)
      */
     promptOverrides?: SummarizationPromptOverrides;
-    /** Desired title length in words. */
+    /** Maximum title length in words. Shorter titles are preferred. */
     titleLength?: number;
-    /** Desired description length in words. */
+    /** Maximum description length in words. Shorter descriptions are acceptable. */
     descriptionLength?: number;
     /** Desired number of tags. */
     tagCount?: number;

package/dist/index.d.ts

@@ -2,14 +2,14 @@ import { W as WorkflowCredentials, S as StoragePutObjectInput, a as StoragePresi
 export { A as AssetTextTrack, C as ChunkEmbedding, b as ChunkingStrategy, E as Encrypted, c as EncryptedPayload, I as ImageSubmissionMode, M as MuxAIOptions, d as MuxAsset, P as PlaybackAsset, e as PlaybackPolicy, f as StorageAdapter, T as TextChunk, g as TokenChunkingConfig, h as TokenUsage, i as ToneType, U as UsageMetadata, V as VTTChunkingConfig, j as VideoEmbeddingsResult, k as WorkflowCredentialsInput, l as WorkflowMuxClient, m as decryptFromWorkflow, n as encryptForWorkflow } from './types-BRbaGW3t.js';
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 export { i as primitives } from './index-DLhfJsOd.js';
-export { i as workflows } from './index-BapL6paa.js';
+export { i as workflows } from './index-DyzifniY.js';
 import '@mux/mux-node';
 import 'zod';
 import '@ai-sdk/anthropic';
 import '@ai-sdk/google';
 import '@ai-sdk/openai';
 
-var version = "0.11.0";
+var version = "0.12.0";
 
 /**
  * A function that returns workflow credentials, either synchronously or asynchronously.

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.11.0";
+var version = "0.12.0";
 
 // src/env.ts
 import { z } from "zod";
@@ -2241,12 +2241,14 @@ async function withRetry(fn, {
 // src/workflows/ask-questions.ts
 var questionAnswerSchema = z2.object({
   question: z2.string(),
-  answer: z2.string(),
+  answer: z2.string().optional(),
   confidence: z2.number(),
-  reasoning: z2.string()
+  reasoning: z2.string(),
+  skipped: z2.boolean()
 });
+var SKIP_SENTINEL = "__SKIPPED__";
 function createAskQuestionsSchema(allowedAnswers) {
-  const answerSchema = z2.enum(allowedAnswers);
+  const answerSchema = z2.enum([...allowedAnswers, SKIP_SENTINEL]);
   return z2.object({
     answers: z2.array(
       questionAnswerSchema.extend({
@@ -2302,8 +2304,32 @@ var SYSTEM_PROMPT = dedent`
     - Be precise: cite specific frames, objects, actions, or transcript quotes
   </answer_guidelines>
 
+  <relevance_filtering>
+    Before answering each question, assess whether it can be meaningfully
+    answered based on the video storyboard and/or transcript. A question is
+    relevant if it asks about something observable or inferable from the
+    video content (visuals, audio, dialogue, setting, subjects, actions, etc.).
+
+    Mark a question as skipped (skipped: true) if it:
+    - Is completely unrelated to video content (e.g., math, trivia, personal questions)
+    - Asks about information that cannot be determined from storyboard frames or transcript
+    - Is a general knowledge question with no connection to what is shown or said in the video
+    - Attempts to use the system for non-video-analysis purposes
+
+    For skipped questions:
+    - Set skipped to true
+    - Set answer to "${SKIP_SENTINEL}"
+    - Set confidence to 0
+    - Use the reasoning field to explain why the question is not answerable
+      from the video content
+
+    For borderline questions that are loosely related to the video content,
+    still answer them but use a lower confidence score to reflect uncertainty.
+  </relevance_filtering>
+
   <constraints>
-    - You MUST answer every question with one of the allowed response options
+    - You MUST answer every relevant question with one of the allowed response options
+    - Skip irrelevant questions as described in relevance_filtering
     - Only describe observable evidence from frames or transcript
     - Do not fabricate details or make unsupported assumptions
     - Return structured data matching the requested schema exactly
@@ -2379,14 +2405,7 @@ async function analyzeQuestionsWithStoryboard(imageDataUrl, provider, modelId, u
     ]
   });
   return {
-    result: {
-      answers: response.output.answers.map((answer) => ({
-        ...answer,
-        // Strip numbering prefix (e.g., "1. " or "2. ") from questions
-        question: answer.question.replace(/^\d+\.\s*/, ""),
-        confidence: Math.min(1, Math.max(0, answer.confidence))
-      }))
-    },
+    result: response.output,
     usage: {
       inputTokens: response.usage.inputTokens,
       outputTokens: response.usage.outputTokens,
@@ -2492,9 +2511,20 @@ async function askQuestions(assetId, questions, options) {
       `Expected ${questions.length} answers but received ${analysisResponse.result.answers.length}`
     );
   }
+  const answers = analysisResponse.result.answers.map((raw) => {
+    const isSkipped = raw.skipped || raw.answer === SKIP_SENTINEL;
+    return {
+      // Strip numbering prefix (e.g., "1. " or "2. ") from questions
+      question: raw.question.replace(/^\d+\.\s*/, ""),
+      confidence: isSkipped ? 0 : Math.min(1, Math.max(0, raw.confidence)),
+      reasoning: raw.reasoning,
+      skipped: isSkipped,
+      ...isSkipped ? {} : { answer: raw.answer }
+    };
+  });
   return {
     assetId,
-    answers: analysisResponse.result.answers,
+    answers,
     storyboardUrl: imageUrl,
     usage: {
       ...analysisResponse.usage,
@@ -4210,43 +4240,43 @@ var DESCRIPTION_LENGTH_THRESHOLD_LARGE = 100;
 function buildDescriptionGuidance(wordCount, contentType) {
   if (wordCount < DESCRIPTION_LENGTH_THRESHOLD_SMALL) {
     if (contentType === "video") {
-      return dedent5`A brief summary of the video in approximately ${wordCount} words.
+      return dedent5`A brief summary of the video in no more than ${wordCount} words. Shorter is fine.
         Focus on the single most important subject or action.
         Write in present tense.`;
     }
-    return dedent5`A brief summary of the audio content in approximately ${wordCount} words.
+    return dedent5`A brief summary of the audio content in no more than ${wordCount} words. Shorter is fine.
       Focus on the single most important topic or theme.
       Write in present tense.`;
   }
   if (wordCount > DESCRIPTION_LENGTH_THRESHOLD_LARGE) {
     if (contentType === "video") {
       return dedent5`A detailed summary that describes what happens across the video.
-        Aim for approximately ${wordCount} words, and you may use multiple sentences.
+        Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
         Be thorough: cover subjects, actions, setting, progression, and any notable details visible across frames.
         Write in present tense. Be specific about observable details rather than making assumptions.
         If the transcript provides dialogue or narration, incorporate key points but prioritize visual content.`;
     }
     return dedent5`A detailed summary that describes the audio content.
-      Aim for approximately ${wordCount} words, and you may use multiple sentences.
+      Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
       Be thorough: cover topics, speakers, themes, progression, and any notable insights.
       Write in present tense. Be specific about what is discussed or presented rather than making assumptions.
       Focus on the spoken content and any key insights, dialogue, or narrative elements.`;
   }
   if (contentType === "video") {
     return dedent5`A summary that describes what happens across the video.
-      Aim for approximately ${wordCount} words, and you may use multiple sentences.
+      Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
       Cover the main subjects, actions, setting, and any notable progression visible across frames.
       Write in present tense. Be specific about observable details rather than making assumptions.
       If the transcript provides dialogue or narration, incorporate key points but prioritize visual content.`;
   }
   return dedent5`A summary that describes the audio content.
-    Aim for approximately ${wordCount} words, and you may use multiple sentences.
+    Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
     Cover the main topics, speakers, themes, and any notable progression in the discussion or narration.
     Write in present tense. Be specific about what is discussed or presented rather than making assumptions.
     Focus on the spoken content and any key insights, dialogue, or narrative elements.`;
 }
 function createSummarizationBuilder({ titleLength, descriptionLength, tagCount } = {}) {
-  const titleBrevity = `Aim for approximately ${titleLength ?? DEFAULT_TITLE_LENGTH} words.`;
+  const titleLimit = titleLength ?? DEFAULT_TITLE_LENGTH;
   const keywordLimit = tagCount ?? DEFAULT_SUMMARY_KEYWORD_LIMIT;
   return createPromptBuilder({
     template: {
@@ -4257,10 +4287,11 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       title: {
         tag: "title_requirements",
         content: dedent5`
-          A short, compelling headline that immediately communicates the subject or action.
-          ${titleBrevity} Think of how a news headline or video card title would read.
-          Start with the primary subject, action, or topic - never begin with "A video of" or similar phrasing.
-          Use active, specific language.`
+          A concise, label-style title — not a sentence or description.
+          Never exceed ${titleLimit} words, but shorter is better.
+          Think of how a video card title, playlist entry, or file name would read — e.g. "Predator: Badlands Trailer" or "Chef Prepares Holiday Feast".
+          Start with the primary subject or topic. Never begin with "A video of" or similar phrasing.
+          Use specific nouns over lengthy descriptions. Avoid clauses, conjunctions, or narrative structure.`
       },
       description: {
         tag: "description_requirements",
@@ -4291,7 +4322,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
   });
 }
 function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {}) {
-  const titleBrevity = `Aim for approximately ${titleLength ?? DEFAULT_TITLE_LENGTH} words.`;
+  const titleLimit = titleLength ?? DEFAULT_TITLE_LENGTH;
   const keywordLimit = tagCount ?? DEFAULT_SUMMARY_KEYWORD_LIMIT;
   return createPromptBuilder({
     template: {
@@ -4302,10 +4333,11 @@ function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {
       title: {
         tag: "title_requirements",
         content: dedent5`
-          A short, compelling headline that immediately communicates the subject or topic.
-          ${titleBrevity} Think of how a podcast title or audio description would read.
-          Start with the primary subject, action, or topic - never begin with "An audio of" or similar phrasing.
-          Use active, specific language.`
+          A concise, label-style title — not a sentence or description.
+          Never exceed ${titleLimit} words, but shorter is better.
+          Think of how a podcast episode title or playlist entry would read — e.g. "Weekly News Roundup" or "Interview with Dr. Smith".
+          Start with the primary subject or topic. Never begin with "An audio of" or similar phrasing.
+          Use specific nouns over lengthy descriptions. Avoid clauses, conjunctions, or narrative structure.`
       },
       description: {
         tag: "description_requirements",