mulmocast 1.2.45 → 1.2.46

package/lib/actions/translate.js

@@ -8,6 +8,7 @@ import { splitText } from "../utils/string.js";
 import { settings2GraphAIConfig, beatId, multiLingualObjectToArray } from "../utils/utils.js";
 import { getMultiLingual } from "../utils/context.js";
 import { currentMulmoScriptVersion } from "../utils/const.js";
+import { translateApiKeyMissingError } from "../utils/error_cause.js";
 import { getOutputMultilingualFilePath, mkdir, writingMessage, hashSHA256 } from "../utils/file.js";
 import { translateSystemPrompt, translatePrompts } from "../utils/prompt.js";
 import { MulmoStudioContextMethods } from "../methods/mulmo_studio_context.js";
@@ -241,7 +242,7 @@ export const translateBeat = async (index, context, targetLangs, args) => {
     try {
         const { outputMultilingualFilePath } = getOutputMultilingualFilePathAndMkdir(context);
         const config = settings2GraphAIConfig(settings, process.env);
-        assert(!!config?.openAIAgent?.apiKey, "The OPENAI_API_KEY environment variable is missing or empty"); // TODO: cause
+        assert(!!config?.openAIAgent?.apiKey, "The OPENAI_API_KEY environment variable is missing or empty", false, translateApiKeyMissingError());
         const graph = new GraphAI(beatGraph, { ...vanillaAgents, fileWriteAgent, openAIAgent }, { agentFilters, config });
         graph.injectValue("context", context);
         graph.injectValue("targetLangs", targetLangs);
@@ -276,7 +277,7 @@ export const translate = async (context, args) => {
             ? args?.targetLangs
             : [...new Set([context.lang, context.studio.script.captionParams?.lang].filter((x) => !isNull(x)))];
         const config = settings2GraphAIConfig(settings, process.env);
-        assert(!!config?.openAIAgent?.apiKey, "The OPENAI_API_KEY environment variable is missing or empty"); // TODO: cause
+        assert(!!config?.openAIAgent?.apiKey, "The OPENAI_API_KEY environment variable is missing or empty", false, translateApiKeyMissingError());
         const graph = new GraphAI(translate_graph_data, { ...vanillaAgents, fileWriteAgent, openAIAgent }, { agentFilters, config });
         graph.injectValue("context", context);
         graph.injectValue("targetLangs", targetLangs);

package/lib/agents/add_bgm_agent.js

@@ -2,14 +2,19 @@ import { GraphAILogger } from "graphai";
 import { FfmpegContextAddInput, FfmpegContextInit, FfmpegContextGenerateOutput, ffmpegGetMediaDuration } from "../utils/ffmpeg_utils.js";
 import { MulmoStudioContextMethods } from "../methods/mulmo_studio_context.js";
 import { isFile } from "../utils/file.js";
+import { agentGenerationError, agentFileNotExistError, audioAction, audioFileTarget } from "../utils/error_cause.js";
 const addBGMAgent = async ({ namedInputs, params, }) => {
     const { voiceFile, outputFile, context } = namedInputs;
     const { musicFile } = params;
     if (!isFile(voiceFile)) {
-        throw new Error(`AddBGMAgent voiceFile not exist: ${voiceFile}`);
+        throw new Error(`AddBGMAgent voiceFile not exist: ${voiceFile}`, {
+            cause: agentFileNotExistError("addBGMAgent", audioAction, audioFileTarget, voiceFile),
+        });
     }
     if (!musicFile.match(/^http/) && !isFile(musicFile)) {
-        throw new Error(`AddBGMAgent musicFile not exist: ${musicFile}`);
+        throw new Error(`AddBGMAgent musicFile not exist: ${musicFile}`, {
+            cause: agentFileNotExistError("addBGMAgent", audioAction, audioFileTarget, musicFile),
+        });
     }
     const { duration: speechDuration } = await ffmpegGetMediaDuration(voiceFile);
     const introPadding = MulmoStudioContextMethods.getIntroPadding(context);
@@ -30,7 +35,9 @@ const addBGMAgent = async ({ namedInputs, params, }) => {
     }
     catch (e) {
         GraphAILogger.log(e);
-        throw new Error(`AddBGMAgent ffmpeg run Error`);
+        throw new Error(`AddBGMAgent ffmpeg run Error`, {
+            cause: agentGenerationError("addBGMAgent", audioAction, audioFileTarget),
+        });
     }
 };
 const addBGMAgentInfo = {

package/lib/agents/image_genai_agent.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { GraphAILogger } from "graphai";
 import { provider2ImageAgent } from "../utils/provider2agent.js";
+import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, imageAction, imageFileTarget, hasCause } from "../utils/error_cause.js";
 import { GoogleGenAI, PersonGeneration } from "@google/genai";
 import { blankImagePath, blankSquareImagePath, blankVerticalImagePath } from "../utils/file.js";
 const getAspectRatio = (canvasSize) => {
@@ -20,7 +21,9 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
     const model = params.model ?? provider2ImageAgent["google"].defaultModel;
     const apiKey = config?.apiKey;
     if (!apiKey) {
-        throw new Error("Google GenAI API key is required (GEMINI_API_KEY)");
+        throw new Error("Google GenAI API key is required (GEMINI_API_KEY)", {
+            cause: apiKeyMissingError("imageGenAIAgent", imageAction, "GEMINI_API_KEY"),
+        });
     }
     try {
         const ai = new GoogleGenAI({ apiKey });
@@ -44,7 +47,9 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
             });
             const response = await ai.models.generateContent({ model, contents });
             if (!response.candidates?.[0]?.content?.parts) {
-                throw new Error("ERROR: generateContent returned no candidates");
+                throw new Error("ERROR: generateContent returned no candidates", {
+                    cause: agentInvalidResponseError("imageGenAIAgent", imageAction, imageFileTarget),
+                });
             }
             for (const part of response.candidates[0].content.parts) {
                 if (part.text) {
@@ -53,13 +58,17 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
                 else if (part.inlineData) {
                     const imageData = part.inlineData.data;
                     if (!imageData) {
-                        throw new Error("ERROR: generateContent returned no image data");
+                        throw new Error("ERROR: generateContent returned no image data", {
+                            cause: agentInvalidResponseError("imageGenAIAgent", imageAction, imageFileTarget),
+                        });
                     }
                     const buffer = Buffer.from(imageData, "base64");
                     return { buffer };
                 }
             }
-            throw new Error("ERROR: generateContent returned no image data");
+            throw new Error("ERROR: generateContent returned no image data", {
+                cause: agentInvalidResponseError("imageGenAIAgent", imageAction, imageFileTarget),
+            });
         }
         else {
             const response = await ai.models.generateImages({
@@ -73,18 +82,27 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
                 },
             });
             if (!response.generatedImages || response.generatedImages.length === 0) {
-                throw new Error("ERROR: generateImage returned no generated images");
+                throw new Error("ERROR: generateImage returned no generated images", {
+                    cause: agentInvalidResponseError("imageGenAIAgent", imageAction, imageFileTarget),
+                });
             }
             const image = response.generatedImages[0].image;
             if (image && image.imageBytes) {
                 return { buffer: Buffer.from(image.imageBytes, "base64") };
             }
-            throw new Error("ERROR: generateImage returned no image bytes");
+            throw new Error("ERROR: generateImage returned no image bytes", {
+                cause: agentInvalidResponseError("imageGenAIAgent", imageAction, imageFileTarget),
+            });
         }
     }
     catch (error) {
         GraphAILogger.info("Failed to generate image:", error);
-        throw error;
+        if (hasCause(error) && error.cause) {
+            throw error;
+        }
+        throw new Error("Failed to generate image with Google GenAI", {
+            cause: agentGenerationError("imageGenAIAgent", imageAction, imageFileTarget),
+        });
     }
 };
 const imageGenAIAgentInfo = {

package/lib/agents/image_openai_agent.js

@@ -3,13 +3,16 @@ import path from "path";
 import { GraphAILogger } from "graphai";
 import OpenAI, { toFile } from "openai";
 import { provider2ImageAgent } from "../utils/provider2agent.js";
+import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, imageAction, imageFileTarget } from "../utils/error_cause.js";
 // https://platform.openai.com/docs/guides/image-generation
 export const imageOpenaiAgent = async ({ namedInputs, params, config, }) => {
     const { prompt, referenceImages } = namedInputs;
     const { moderation, canvasSize, quality } = params;
     const { apiKey, baseURL } = { ...config };
     if (!apiKey) {
-        throw new Error("OpenAI API key is required (OPENAI_API_KEY)");
+        throw new Error("OpenAI API key is required (OPENAI_API_KEY)", {
+            cause: apiKeyMissingError("imageOpenaiAgent", imageAction, "OPENAI_API_KEY"),
+        });
     }
     const model = params.model ?? provider2ImageAgent["openai"].defaultModel;
     const openai = new OpenAI({ apiKey, baseURL });
@@ -67,25 +70,33 @@ export const imageOpenaiAgent = async ({ namedInputs, params, config, }) => {
         }
         catch (error) {
             GraphAILogger.info("Failed to generate image:", error.message);
-            throw error;
+            throw new Error("Failed to generate image with OpenAI", {
+                cause: agentGenerationError("imageOpenaiAgent", imageAction, imageFileTarget),
+            });
         }
     })();
     if (!response.data) {
-        throw new Error(`response.data is undefined: ${response}`);
+        throw new Error(`response.data is undefined: ${response}`, {
+            cause: agentInvalidResponseError("imageOpenaiAgent", imageAction, imageFileTarget),
+        });
     }
     const url = response.data[0].url;
     if (!url) {
         // For gpt-image-1
         const image_base64 = response.data[0].b64_json;
         if (!image_base64) {
-            throw new Error(`response.data[0].b64_json is undefined: ${response}`);
+            throw new Error(`response.data[0].b64_json is undefined: ${response}`, {
+                cause: agentInvalidResponseError("imageOpenaiAgent", imageAction, imageFileTarget),
+            });
         }
         return { buffer: Buffer.from(image_base64, "base64") };
     }
     // For dall-e-3
     const res = await fetch(url);
     if (!res.ok) {
-        throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+        throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`, {
+            cause: agentGenerationError("imageOpenaiAgent", imageAction, imageFileTarget),
+        });
     }
     // 2. Read the response as an ArrayBuffer
     const arrayBuffer = await res.arrayBuffer();

package/lib/agents/image_replicate_agent.js

@@ -2,6 +2,7 @@ import { readFileSync } from "fs";
 import { GraphAILogger } from "graphai";
 import Replicate from "replicate";
 import { getAspectRatio } from "./movie_replicate_agent.js";
+import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, imageAction, imageFileTarget, hasCause } from "../utils/error_cause.js";
 import { provider2ImageAgent } from "../utils/provider2agent.js";
 export const imageReplicateAgent = async ({ namedInputs, params, config, }) => {
     const { prompt, referenceImages } = namedInputs;
@@ -9,7 +10,9 @@ export const imageReplicateAgent = async ({ namedInputs, params, config, }) => {
     const model = params.model ?? provider2ImageAgent.replicate.defaultModel;
     const apiKey = config?.apiKey;
     if (!apiKey) {
-        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)");
+        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)", {
+            cause: apiKeyMissingError("imageReplicateAgent", imageAction, "REPLICATE_API_TOKEN"),
+        });
     }
     const replicate = new Replicate({
         auth: apiKey,
@@ -31,17 +34,26 @@ export const imageReplicateAgent = async ({ namedInputs, params, config, }) => {
             const imageUrl = output[0].url();
             const imageResponse = await fetch(imageUrl);
             if (!imageResponse.ok) {
-                throw new Error(`Error downloading video: ${imageResponse.status} - ${imageResponse.statusText}`);
+                throw new Error(`Error downloading image: ${imageResponse.status} - ${imageResponse.statusText}`, {
+                    cause: agentGenerationError("imageReplicateAgent", imageAction, imageFileTarget),
+                });
             }
             const arrayBuffer = await imageResponse.arrayBuffer();
             const buffer = Buffer.from(arrayBuffer);
             return { buffer };
         }
-        throw new Error("ERROR: generateImage returned undefined");
+        throw new Error("ERROR: generateImage returned undefined", {
+            cause: agentInvalidResponseError("imageReplicateAgent", imageAction, imageFileTarget),
+        });
     }
     catch (error) {
         GraphAILogger.info("Replicate generation error:", error);
-        throw error;
+        if (hasCause(error) && error.cause) {
+            throw error;
+        }
+        throw new Error("Failed to generate image with Replicate", {
+            cause: agentGenerationError("imageReplicateAgent", imageAction, imageFileTarget),
+        });
     }
 };
 const imageReplicateAgentInfo = {

package/lib/agents/lipsync_replicate_agent.js

@@ -2,24 +2,31 @@ import { readFileSync, existsSync } from "fs";
 import { GraphAILogger } from "graphai";
 import Replicate from "replicate";
 import { provider2LipSyncAgent } from "../utils/provider2agent.js";
+import { apiKeyMissingError, agentGenerationError, agentFileNotExistError, imageAction, movieFileTarget, audioFileTarget, hasCause, } from "../utils/error_cause.js";
 export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) => {
     const { movieFile, audioFile, imageFile } = namedInputs;
     const apiKey = config?.apiKey;
     const model = params.model ?? provider2LipSyncAgent.replicate.defaultModel;
     if (!apiKey) {
-        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)");
+        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)", {
+            cause: apiKeyMissingError("lipSyncReplicateAgent", imageAction, "REPLICATE_API_TOKEN"),
+        });
     }
     const replicate = new Replicate({
         auth: apiKey,
     });
     if (!audioFile || !existsSync(audioFile)) {
-        throw new Error(`lipSyncReplicateAgent audioFile not exist: ${audioFile}`);
+        throw new Error(`lipSyncReplicateAgent audioFile not exist: ${audioFile}`, {
+            cause: agentFileNotExistError("lipSyncReplicateAgent", imageAction, audioFileTarget, audioFile),
+        });
     }
     const audioBuffer = readFileSync(audioFile);
     const videoBuffer = movieFile ? readFileSync(movieFile) : undefined;
     const imageBuffer = imageFile ? readFileSync(imageFile) : undefined;
     if (!videoBuffer && !imageBuffer) {
-        throw new Error("lipSyncReplicateAgent Either movieFile or imageFile is required");
+        throw new Error("lipSyncReplicateAgent Either movieFile or imageFile is required", {
+            cause: agentGenerationError("lipSyncReplicateAgent", imageAction, movieFileTarget),
+        });
     }
     const audioUri = `data:audio/wav;base64,${audioBuffer.toString("base64")}`;
     const videoUri = videoBuffer ? `data:video/quicktime;base64,${videoBuffer.toString("base64")}` : undefined;
@@ -35,7 +42,9 @@ export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) =>
     };
     const modelParams = provider2LipSyncAgent.replicate.modelParams[model];
     if (!modelParams) {
-        throw new Error(`Model ${model} is not supported`);
+        throw new Error(`Model ${model} is not supported`, {
+            cause: agentGenerationError("lipSyncReplicateAgent", imageAction, movieFileTarget),
+        });
     }
     const videoParam = modelParams.video;
     const audioParam = modelParams.audio;
@@ -58,7 +67,9 @@ export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) =>
             const videoUrl = output.url();
             const videoResponse = await fetch(videoUrl);
             if (!videoResponse.ok) {
-                throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`);
+                throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
+                    cause: agentGenerationError("lipSyncReplicateAgent", imageAction, movieFileTarget),
+                });
             }
             const arrayBuffer = await videoResponse.arrayBuffer();
             return { buffer: Buffer.from(arrayBuffer) };
@@ -67,7 +78,12 @@ export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) =>
     }
     catch (error) {
         GraphAILogger.info("Failed to generate lip sync:", error.message);
-        throw error;
+        if (hasCause(error) && error.cause) {
+            throw error;
+        }
+        throw new Error("Failed to lipSync with Replicate", {
+            cause: agentGenerationError("lipSyncReplicateAgent", imageAction, movieFileTarget),
+        });
     }
 };
 const lipSyncReplicateAgentInfo = {

package/lib/agents/movie_genai_agent.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "fs";
 import { GraphAILogger, sleep } from "graphai";
+import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, imageAction, movieFileTarget, hasCause } from "../utils/error_cause.js";
 import { GoogleGenAI, PersonGeneration } from "@google/genai";
 export const getAspectRatio = (canvasSize) => {
     if (canvasSize.width > canvasSize.height) {
@@ -19,7 +20,9 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
     const duration = params.duration ?? 8;
     const apiKey = config?.apiKey;
     if (!apiKey) {
-        throw new Error("Google GenAI API key is required (GEMINI_API_KEY)");
+        throw new Error("Google GenAI API key is required (GEMINI_API_KEY)", {
+            cause: apiKeyMissingError("movieGenAIAgent", imageAction, "GEMINI_API_KEY"),
+        });
     }
     try {
         const ai = new GoogleGenAI({ apiKey });
@@ -55,11 +58,15 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
             response.operation = await ai.operations.getVideosOperation(response);
         }
         if (!response.operation.response?.generatedVideos) {
-            throw new Error(`No video: ${JSON.stringify(response.operation, null, 2)}`);
+            throw new Error(`No video: ${JSON.stringify(response.operation, null, 2)}`, {
+                cause: agentInvalidResponseError("movieGenAIAgent", imageAction, movieFileTarget),
+            });
         }
         const video = response.operation.response.generatedVideos[0].video;
         if (!video) {
-            throw new Error(`No video: ${JSON.stringify(response.operation, null, 2)}`);
+            throw new Error(`No video: ${JSON.stringify(response.operation, null, 2)}`, {
+                cause: agentInvalidResponseError("movieGenAIAgent", imageAction, movieFileTarget),
+            });
         }
         await ai.files.download({
             file: video,
@@ -70,7 +77,12 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
     }
     catch (error) {
         GraphAILogger.info("Failed to generate movie:", error.message);
-        throw error;
+        if (hasCause(error) && error.cause) {
+            throw error;
+        }
+        throw new Error("Failed to generate movie with Google GenAI", {
+            cause: agentGenerationError("movieGenAIAgent", imageAction, movieFileTarget),
+        });
     }
 };
 const movieGenAIAgentInfo = {

package/lib/agents/movie_replicate_agent.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "fs";
 import { GraphAILogger } from "graphai";
 import Replicate from "replicate";
+import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, imageAction, movieFileTarget } from "../utils/error_cause.js";
 import { provider2MovieAgent } from "../utils/provider2agent.js";
 async function generateMovie(model, apiKey, prompt, imagePath, aspectRatio, duration) {
     const replicate = new Replicate({
@@ -28,7 +29,9 @@ async function generateMovie(model, apiKey, prompt, imagePath, aspectRatio, dura
             input[start_image] = base64Image;
         }
         else if (start_image === undefined) {
-            throw new Error(`Model ${model} does not support image-to-video generation`);
+            throw new Error(`Model ${model} does not support image-to-video generation`, {
+                cause: agentGenerationError("movieReplicateAgent", imageAction, movieFileTarget),
+            });
         }
         else {
             input.image = base64Image;
@@ -41,7 +44,9 @@ async function generateMovie(model, apiKey, prompt, imagePath, aspectRatio, dura
             const videoUrl = output.url();
             const videoResponse = await fetch(videoUrl);
             if (!videoResponse.ok) {
-                throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`);
+                throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
+                    cause: agentGenerationError("movieReplicateAgent", imageAction, movieFileTarget),
+                });
             }
             const arrayBuffer = await videoResponse.arrayBuffer();
             return Buffer.from(arrayBuffer);
@@ -71,7 +76,9 @@ export const movieReplicateAgent = async ({ namedInputs, params, config, }) => {
     const aspectRatio = getAspectRatio(params.canvasSize);
     const model = params.model ?? provider2MovieAgent.replicate.defaultModel;
     if (!provider2MovieAgent.replicate.modelParams[model]) {
-        throw new Error(`Model ${model} is not supported`);
+        throw new Error(`Model ${model} is not supported`, {
+            cause: agentGenerationError("movieReplicateAgent", imageAction, movieFileTarget),
+        });
     }
     const duration = (() => {
         const durations = provider2MovieAgent.replicate.modelParams[model].durations;
@@ -84,23 +91,28 @@ export const movieReplicateAgent = async ({ namedInputs, params, config, }) => {
         }
     })();
     if (!provider2MovieAgent.replicate.modelParams[model].durations.includes(duration)) {
-        throw new Error(`Duration ${duration} is not supported for model ${model}. Supported durations: ${provider2MovieAgent.replicate.modelParams[model].durations.join(", ")}`);
+        throw new Error(`Duration ${duration} is not supported for model ${model}. Supported durations: ${provider2MovieAgent.replicate.modelParams[model].durations.join(", ")}`, {
+            cause: agentGenerationError("movieReplicateAgent", imageAction, movieFileTarget),
+        });
     }
     const apiKey = config?.apiKey;
     if (!apiKey) {
-        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)");
+        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)", {
+            cause: apiKeyMissingError("movieReplicateAgent", imageAction, "REPLICATE_API_TOKEN"),
+        });
     }
     try {
         const buffer = await generateMovie(model, apiKey, prompt, imagePath, aspectRatio, duration);
         if (buffer) {
             return { buffer };
         }
-        throw new Error("ERROR: generateMovie returned undefined");
     }
     catch (error) {
         GraphAILogger.info("Failed to generate movie:", error.message);
-        throw error;
     }
+    throw new Error("ERROR: generateMovie returned undefined", {
+        cause: agentInvalidResponseError("movieReplicateAgent", imageAction, movieFileTarget),
+    });
 };
 const movieReplicateAgentInfo = {
     name: "movieReplicateAgent",

package/lib/agents/sound_effect_replicate_agent.js

@@ -2,12 +2,15 @@ import { readFileSync } from "fs";
 import { GraphAILogger } from "graphai";
 import Replicate from "replicate";
 import { provider2SoundEffectAgent } from "../utils/provider2agent.js";
+import { apiKeyMissingError, agentGenerationError, imageAction, movieFileTarget, hasCause } from "../utils/error_cause.js";
 export const soundEffectReplicateAgent = async ({ namedInputs, params, config }) => {
     const { prompt, movieFile } = namedInputs;
     const apiKey = config?.apiKey;
     const model = params.model ?? provider2SoundEffectAgent.replicate.defaultModel;
     if (!apiKey) {
-        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)");
+        throw new Error("Replicate API key is required (REPLICATE_API_TOKEN)", {
+            cause: apiKeyMissingError("soundEffectReplicateAgent", imageAction, "REPLICATE_API_TOKEN"),
+        });
     }
     const replicate = new Replicate({
         auth: apiKey,
@@ -32,7 +35,9 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
             const videoUrl = output.url();
             const videoResponse = await fetch(videoUrl);
             if (!videoResponse.ok) {
-                throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`);
+                throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
+                    cause: agentGenerationError("soundEffectReplicateAgent", imageAction, movieFileTarget),
+                });
             }
             const arrayBuffer = await videoResponse.arrayBuffer();
             return { buffer: Buffer.from(arrayBuffer) };
@@ -41,7 +46,12 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
     }
     catch (error) {
         GraphAILogger.info("Failed to generate sound effect:", error.message);
-        throw error;
+        if (hasCause(error) && error.cause) {
+            throw error;
+        }
+        throw new Error("Failed to generate sound effect with Replicate", {
+            cause: agentGenerationError("soundEffectReplicateAgent", imageAction, movieFileTarget),
+        });
     }
 };
 const soundEffectReplicateAgentInfo = {

package/lib/agents/tavily_agent.js

@@ -1,5 +1,6 @@
 import { assert } from "graphai";
 import { tavily } from "@tavily/core";
+import { apiKeyMissingError, agentGenerationError } from "../utils/error_cause.js";
 const getTavilyApiKey = (params, config) => {
     if (params?.apiKey) {
         return params.apiKey;
@@ -14,7 +15,7 @@ export const tavilySearchAgent = async ({ namedInputs, params, config, }) => {
     assert(!!query, "tavilySearchAgent: query is required! set inputs: { query: 'search terms' }");
     try {
         const apiKey = getTavilyApiKey(params, config);
-        assert(apiKey, "Tavily API key is required. Please set the TAVILY_API_KEY environment variable or provide it in params/config.");
+        assert(apiKey, "Tavily API key is required. Please set the TAVILY_API_KEY environment variable or provide it in params/config.", false, apiKeyMissingError("tavilySearchAgent", "search", "TAVILY_API_KEY"));
         const tvly = tavily({ apiKey });
         // Convert params to SDK options format
         const sdkOptions = {};
@@ -30,7 +31,9 @@ export const tavilySearchAgent = async ({ namedInputs, params, config, }) => {
         return response;
     }
     catch (error) {
-        throw new Error(`Tavily search failed: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Tavily search failed: ${error instanceof Error ? error.message : String(error)}`, {
+            cause: agentGenerationError("tavilySearchAgent", "search", "searchResults"),
+        });
     }
 };
 const tavilySearchAgentInfo = {

package/lib/agents/tts_elevenlabs_agent.js

@@ -1,14 +1,19 @@
 import { GraphAILogger } from "graphai";
 import { provider2TTSAgent } from "../utils/provider2agent.js";
+import { apiKeyMissingError, agentGenerationError, audioAction, audioFileTarget } from "../utils/error_cause.js";
 export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
     const { text } = namedInputs;
     const { voice, model, stability, similarityBoost, suppressError } = params;
     const apiKey = config?.apiKey;
     if (!apiKey) {
-        throw new Error("ElevenLabs API key is required (ELEVENLABS_API_KEY)");
+        throw new Error("ElevenLabs API key is required (ELEVENLABS_API_KEY)", {
+            cause: apiKeyMissingError("ttsElevenlabsAgent", audioAction, "ELEVENLABS_API_KEY"),
+        });
     }
     if (!voice) {
-        throw new Error("ELEVENLABS Voice ID is required");
+        throw new Error("ELEVENLABS Voice ID is required", {
+            cause: agentGenerationError("ttsElevenlabsAgent", audioAction, audioFileTarget),
+        });
     }
     try {
         const requestBody = {
@@ -30,7 +35,9 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
             body: JSON.stringify(requestBody),
         });
         if (!response.ok) {
-            throw new Error(`Eleven Labs API error: ${response.status} ${response.statusText}`);
+            throw new Error(`Eleven Labs API error: ${response.status} ${response.statusText}`, {
+                cause: agentGenerationError("ttsElevenlabsAgent", audioAction, audioFileTarget),
+            });
         }
         const arrayBuffer = await response.arrayBuffer();
         const buffer = Buffer.from(arrayBuffer);
@@ -43,7 +50,9 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
             };
         }
         GraphAILogger.info(e);
-        throw new Error("TTS Eleven Labs Error");
+        throw new Error("TTS Eleven Labs Error", {
+            cause: agentGenerationError("ttsElevenlabsAgent", audioAction, audioFileTarget),
+        });
     }
 };
 const ttsElevenlabsAgentInfo = {

package/lib/agents/tts_google_agent.js

@@ -1,5 +1,6 @@
 import { GraphAILogger } from "graphai";
 import * as textToSpeech from "@google-cloud/text-to-speech";
+import { agentGenerationError, audioAction, audioFileTarget } from "../utils/error_cause.js";
 const client = new textToSpeech.TextToSpeechClient();
 export const ttsGoogleAgent = async ({ namedInputs, params }) => {
     const { text } = namedInputs;
@@ -33,7 +34,9 @@ export const ttsGoogleAgent = async ({ namedInputs, params }) => {
             };
         }
         GraphAILogger.info(e);
-        throw new Error("TTS Google Error");
+        throw new Error("TTS Google Error", {
+            cause: agentGenerationError("ttsGoogleAgent", audioAction, audioFileTarget),
+        });
     }
 };
 const ttsGoogleAgentInfo = {

package/lib/agents/tts_nijivoice_agent.js

@@ -1,4 +1,5 @@
 import { GraphAILogger } from "graphai";
+import { apiKeyMissingError, agentGenerationError, audioAction, audioFileTarget } from "../utils/error_cause.js";
 /*
 const errorMessage = [
   "TTS NijiVoice: No API key. ",
@@ -12,7 +13,9 @@ export const ttsNijivoiceAgent = async ({ params, namedInputs, config, }) => {
     const { apiKey } = config ?? {};
     const { text } = namedInputs;
     if (!apiKey) {
-        throw new Error("NijiVoice API key is required (NIJIVOICE_API_KEY)");
+        throw new Error("NijiVoice API key is required (NIJIVOICE_API_KEY)", {
+            cause: apiKeyMissingError("ttsNijivoiceAgent", audioAction, "NIJIVOICE_API_KEY"),
+        });
     }
     const url = `https://api.nijivoice.com/api/platform/v1/voice-actors/${voice}/generate-voice`;
     const options = {
@@ -42,7 +45,9 @@ export const ttsNijivoiceAgent = async ({ params, namedInputs, config, }) => {
             };
         }
         GraphAILogger.info(voiceJson);
-        throw new Error("TTS Nijivoice Error");
+        throw new Error("TTS Nijivoice Error", {
+            cause: agentGenerationError("ttsNijivoiceAgent", audioAction, audioFileTarget),
+        });
     }
     catch (e) {
         if (suppressError) {
@@ -51,7 +56,9 @@ export const ttsNijivoiceAgent = async ({ params, namedInputs, config, }) => {
             };
         }
         GraphAILogger.info(e);
-        throw new Error("TTS Nijivoice Error");
+        throw new Error("TTS Nijivoice Error", {
+            cause: agentGenerationError("ttsNijivoiceAgent", audioAction, audioFileTarget),
+        });
     }
 };
 const ttsNijivoiceAgentInfo = {

package/lib/agents/tts_openai_agent.js

@@ -1,12 +1,15 @@
 import { GraphAILogger } from "graphai";
 import OpenAI from "openai";
 import { provider2TTSAgent } from "../utils/provider2agent.js";
+import { apiKeyMissingError, agentGenerationError, audioAction, audioFileTarget } from "../utils/error_cause.js";
 export const ttsOpenaiAgent = async ({ namedInputs, params, config, }) => {
     const { text } = namedInputs;
     const { model, voice, suppressError, instructions } = params;
     const { apiKey, baseURL } = config ?? {};
     if (!apiKey) {
-        throw new Error("OpenAI API key is required (OPENAI_API_KEY)");
+        throw new Error("OpenAI API key is required (OPENAI_API_KEY)", {
+            cause: apiKeyMissingError("ttsOpenaiAgent", audioAction, "OPENAI_API_KEY"),
+        });
     }
     const openai = new OpenAI({ apiKey, baseURL });
     try {
@@ -33,12 +36,16 @@ export const ttsOpenaiAgent = async ({ namedInputs, params, config, }) => {
         if (e && typeof e === "object" && "error" in e) {
             GraphAILogger.info("tts_openai_agent: ");
             GraphAILogger.info(e.error);
-            throw new Error("TTS OpenAI Error: " + JSON.stringify(e.error, null, 2));
+            throw new Error("TTS OpenAI Error: " + JSON.stringify(e.error, null, 2), {
+                cause: agentGenerationError("ttsOpenaiAgent", audioAction, audioFileTarget),
+            });
         }
         else if (e instanceof Error) {
             GraphAILogger.info("tts_openai_agent: ");
             GraphAILogger.info(e.message);
-            throw new Error("TTS OpenAI Error: " + e.message);
+            throw new Error("TTS OpenAI Error: " + e.message, {
+                cause: agentGenerationError("ttsOpenaiAgent", audioAction, audioFileTarget),
+            });
         }
     }
 };

package/lib/utils/error_cause.d.ts

@@ -1,39 +1,98 @@
+/**
+ * Error Definitions for i18n Notifications
+ * ----------------------------------------
+ * This file provides a set of standardized error action/type/target constants
+ * and factory functions that enrich error objects with structured metadata.
+ *
+ * ## Purpose
+ * - Attach `cause` data to `Error` objects for vue-i18n.
+ * - Generate consistent i18n keys in the form:
+ *     notify.error.{action}.{type}[.{target}]
+ * - Provide contextual data (e.g., beatIndex, fileName, agentName) for use in
+ *   translation strings.
+ *
+ * ## Constants
+ * - `type`: describes the error type (e.g., fileNotExist, urlFileNotFound).
+ * - `action`: the operation being performed (e.g., movie, image, audio).
+ * - `target`: the resource involved (e.g., audioFile, imageFile).
+ *
+ * ## Factory Functions
+ * Each factory function (e.g., getAudioInputIdsError, audioCheckerError) returns
+ * a plain object with:
+ *   - `type`      → error type constant
+ *   - `action`    → action constant
+ *   - `target`    → target constant (optional)
+ *   - `agentName` → name of the agent/tool that produced the error
+ *   - `beatIndex` → index of the beat in the current script
+ *   - `fileName`  → file name or identifier (if relevant)
+ *
+ * ## i18n Integration
+ * - The UI consumes the generated `{ action, type, target, ... }` to build the i18n key.
+ * - Example:
+ *     notify.error.movie.fileNotExist.audioFile
+ * - Interpolation values (beatIndex, fileName, etc.) are passed as `data` for
+ *   translations.
+ *
+ * ## Notes
+ * - If `target` is not required, omit it.
+ * - When adding new actions/types/targets, check for consistency with existing ones.
+ * - Use descriptive but concise names to avoid translation conflicts.
+ *
+ * ## Usage in Error Handling
+ * - When throwing manually:
+ *     `throw new Error("message", { cause });`
+ * - When using assertions:
+ *     `assert(condition, message, false, causeObject);`
+ *   (set the 3rd parameter to `false` and pass the `cause` object as the 4th)
+ */
 export declare const urlFileNotFoundType = "urlFileNotFound";
 export declare const fileNotExistType = "fileNotExist";
 export declare const unknownMediaType = "unknownMedia";
 export declare const sourceUndefinedType = "undefinedSourceType";
+export declare const apiErrorType = "apiError";
+export declare const apiKeyMissingType = "apiKeyMissing";
+export declare const invalidResponseType = "invalidResponse";
 export declare const movieAction = "movie";
 export declare const imageAction = "images";
 export declare const audioAction = "audio";
 export declare const imageReferenceAction = "imageReference";
+export declare const translateAction = "translate";
 export declare const audioFileTarget = "audioFile";
 export declare const imageFileTarget = "imageFile";
 export declare const movieFileTarget = "movieFile";
 export declare const videoSourceTarget = "videoSource";
 export declare const audioSourceTarget = "audioSource";
 export declare const codeTextTarget = "codeText";
+export declare const agentFileNotExistError: (agentName: string, action: string, target: string, fileName: string, beatIndex?: number) => {
+    beatIndex?: number | undefined;
+    type: string;
+    action: string;
+    target: string;
+    agentName: string;
+    fileName: string;
+};
 export declare const getAudioInputIdsError: (index: number, fileName: string) => {
+    beatIndex?: number | undefined;
     type: string;
     action: string;
     target: string;
     agentName: string;
-    beatIndex: number;
     fileName: string;
 };
 export declare const audioCheckerError: (index: number, fileName: string) => {
+    beatIndex?: number | undefined;
     type: string;
     action: string;
     target: string;
     agentName: string;
-    beatIndex: number;
     fileName: string;
 };
 export declare const createVideoFileError: (index: number, fileName: string) => {
+    beatIndex?: number | undefined;
     type: string;
     action: string;
     target: string;
     agentName: string;
-    beatIndex: number;
     fileName: string;
 };
 export declare const createVideoSourceError: (index: number) => {
@@ -82,3 +141,32 @@ export declare const imagePluginUnknownMediaError: (imageType: string) => {
     action: string;
     target: string;
 };
+export declare const apiKeyMissingError: (agentName: string, action: string, envVarName: string) => {
+    type: string;
+    action: string;
+    agentName: string;
+    envVarName: string;
+};
+export declare const agentGenerationError: (agentName: string, action: string, target: string, beatIndex?: number) => {
+    beatIndex?: number | undefined;
+    type: string;
+    action: string;
+    target: string;
+    agentName: string;
+};
+export declare const agentInvalidResponseError: (agentName: string, action: string, target: string, beatIndex?: number) => {
+    beatIndex?: number | undefined;
+    type: string;
+    action: string;
+    target: string;
+    agentName: string;
+};
+export declare const translateApiKeyMissingError: () => {
+    type: string;
+    action: string;
+    agentName: string;
+    envVarName: string;
+};
+export declare const hasCause: (err: unknown) => err is Error & {
+    cause: unknown;
+};

package/lib/utils/error_cause.js

@@ -1,46 +1,90 @@
+/**
+ * Error Definitions for i18n Notifications
+ * ----------------------------------------
+ * This file provides a set of standardized error action/type/target constants
+ * and factory functions that enrich error objects with structured metadata.
+ *
+ * ## Purpose
+ * - Attach `cause` data to `Error` objects for vue-i18n.
+ * - Generate consistent i18n keys in the form:
+ *     notify.error.{action}.{type}[.{target}]
+ * - Provide contextual data (e.g., beatIndex, fileName, agentName) for use in
+ *   translation strings.
+ *
+ * ## Constants
+ * - `type`: describes the error type (e.g., fileNotExist, urlFileNotFound).
+ * - `action`: the operation being performed (e.g., movie, image, audio).
+ * - `target`: the resource involved (e.g., audioFile, imageFile).
+ *
+ * ## Factory Functions
+ * Each factory function (e.g., getAudioInputIdsError, audioCheckerError) returns
+ * a plain object with:
+ *   - `type`      → error type constant
+ *   - `action`    → action constant
+ *   - `target`    → target constant (optional)
+ *   - `agentName` → name of the agent/tool that produced the error
+ *   - `beatIndex` → index of the beat in the current script
+ *   - `fileName`  → file name or identifier (if relevant)
+ *
+ * ## i18n Integration
+ * - The UI consumes the generated `{ action, type, target, ... }` to build the i18n key.
+ * - Example:
+ *     notify.error.movie.fileNotExist.audioFile
+ * - Interpolation values (beatIndex, fileName, etc.) are passed as `data` for
+ *   translations.
+ *
+ * ## Notes
+ * - If `target` is not required, omit it.
+ * - When adding new actions/types/targets, check for consistency with existing ones.
+ * - Use descriptive but concise names to avoid translation conflicts.
+ *
+ * ## Usage in Error Handling
+ * - When throwing manually:
+ *     `throw new Error("message", { cause });`
+ * - When using assertions:
+ *     `assert(condition, message, false, causeObject);`
+ *   (set the 3rd parameter to `false` and pass the `cause` object as the 4th)
+ */
+// Error Types
 export const urlFileNotFoundType = "urlFileNotFound";
 export const fileNotExistType = "fileNotExist";
 export const unknownMediaType = "unknownMedia";
 export const sourceUndefinedType = "undefinedSourceType";
+export const apiErrorType = "apiError";
+export const apiKeyMissingType = "apiKeyMissing";
+export const invalidResponseType = "invalidResponse";
+// Actions
 export const movieAction = "movie";
 export const imageAction = "images";
 export const audioAction = "audio";
 export const imageReferenceAction = "imageReference";
+export const translateAction = "translate";
+// Targets
 export const audioFileTarget = "audioFile";
 export const imageFileTarget = "imageFile";
 export const movieFileTarget = "movieFile";
 export const videoSourceTarget = "videoSource";
 export const audioSourceTarget = "audioSource";
 export const codeTextTarget = "codeText";
-export const getAudioInputIdsError = (index, fileName) => {
+// Agent File Not Exist Errors
+export const agentFileNotExistError = (agentName, action, target, fileName, beatIndex) => {
     return {
         type: fileNotExistType,
-        action: movieAction,
-        target: audioFileTarget,
-        agentName: "combineAudioFiles",
-        beatIndex: index,
+        action,
+        target,
+        agentName,
         fileName,
+        ...(beatIndex !== undefined && { beatIndex }),
     };
 };
+export const getAudioInputIdsError = (index, fileName) => {
+    return agentFileNotExistError("combineAudioFiles", movieAction, audioFileTarget, fileName, index);
+};
 export const audioCheckerError = (index, fileName) => {
-    return {
-        type: fileNotExistType,
-        action: imageAction,
-        target: imageFileTarget,
-        agentName: "audioChecker",
-        beatIndex: index,
-        fileName,
-    };
+    return agentFileNotExistError("audioChecker", imageAction, imageFileTarget, fileName, index);
 };
 export const createVideoFileError = (index, fileName) => {
-    return {
-        type: fileNotExistType,
-        action: movieAction,
-        target: imageFileTarget,
-        agentName: "createVideo",
-        beatIndex: index,
-        fileName,
-    };
+    return agentFileNotExistError("createVideo", movieAction, imageFileTarget, fileName, index);
 };
 // undefinedSource
 export const createVideoSourceError = (index) => {
@@ -105,3 +149,44 @@ export const imagePluginUnknownMediaError = (imageType) => {
         target: imageType,
     };
 };
+// Agent API Key Errors
+export const apiKeyMissingError = (agentName, action, envVarName) => {
+    return {
+        type: apiKeyMissingType,
+        action,
+        agentName,
+        envVarName,
+    };
+};
+// Agent API/Generation Errors
+export const agentGenerationError = (agentName, action, target, beatIndex) => {
+    return {
+        type: apiErrorType,
+        action,
+        target,
+        agentName,
+        ...(beatIndex !== undefined && { beatIndex }),
+    };
+};
+// Agent Invalid Response Errors
+export const agentInvalidResponseError = (agentName, action, target, beatIndex) => {
+    return {
+        type: invalidResponseType,
+        action,
+        target,
+        agentName,
+        ...(beatIndex !== undefined && { beatIndex }),
+    };
+};
+// Translation Errors
+export const translateApiKeyMissingError = () => {
+    return {
+        type: apiKeyMissingType,
+        action: translateAction,
+        agentName: "translate",
+        envVarName: "OPENAI_API_KEY",
+    };
+};
+export const hasCause = (err) => {
+    return err instanceof Error && "cause" in err;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "1.2.45",
+  "version": "1.2.46",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",