mulmocast 2.6.20 → 2.6.22

package/lib/agents/tts_kotodama_agent.js

@@ -44,7 +44,15 @@ export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
             });
         }
         const buffer = Buffer.from(json.audios[0], "base64");
-        return { buffer };
+        // Kotodama is subscription-billed externally (no public per-char rate API
+        // surface). Report inputChars + voice/decoration so the billing layer can
+        // do its own accounting.
+        const usage = {
+            provider: "kotodama",
+            model: body.speaker_id,
+            inputChars: text.length,
+        };
+        return { buffer, usage };
     }
     catch (error) {
         if (suppressError) {

package/lib/agents/tts_openai_agent.js

@@ -28,7 +28,15 @@ export const ttsOpenaiAgent = async ({ namedInputs, params, config, }) => {
         GraphAILogger.log("ttsOptions", tts_options);
         const response = await openai.audio.speech.create(tts_options);
         const buffer = Buffer.from(await response.arrayBuffer());
-        return { buffer };
+        // tts-1 / tts-1-hd bill per character. gpt-4o-mini-tts is token-based and
+        // is handled by #1428; for now we report inputChars uniformly and let the
+        // billing layer pick the right unit from `model`.
+        const usage = {
+            provider: "openai",
+            model: tts_options.model,
+            inputChars: text.length,
+        };
+        return { buffer, usage };
     }
     catch (error) {
         if (suppressError) {

package/lib/cli/commands/audio/handler.js

@@ -1,5 +1,5 @@
 import { audio } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -7,4 +7,5 @@ export const handler = async (argv) => {
     }
     await runTranslateIfNeeded(context);
     await audio(context);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/bundle/handler.js

@@ -1,5 +1,5 @@
 import { mulmoViewerBundle, audio, images, translate } from "../../../actions/index.js";
-import { initializeContext } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext } from "../../helpers.js";
 import { bundleTargetLang } from "../../../types/const.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
@@ -11,4 +11,5 @@ export const handler = async (argv) => {
         await audio({ ...context, lang });
     }
     await audio(context).then(images).then(mulmoViewerBundle);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/html/handler.js

@@ -1,5 +1,5 @@
 import { images, html } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -8,4 +8,5 @@ export const handler = async (argv) => {
     await runTranslateIfNeeded(context);
     await images(context);
     await html(context, argv.image_width);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/image/handler.js

@@ -1,5 +1,5 @@
 import { images } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -7,4 +7,5 @@ export const handler = async (argv) => {
     }
     await runTranslateIfNeeded(context);
     await images(context);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/markdown/handler.js

@@ -1,5 +1,5 @@
 import { images, markdown } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -8,4 +8,5 @@ export const handler = async (argv) => {
     await runTranslateIfNeeded(context);
     await images(context);
     await markdown(context, argv.image_width);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/movie/handler.js

@@ -1,5 +1,5 @@
 import { audio, images, movie, captions } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -7,4 +7,5 @@ export const handler = async (argv) => {
     }
     await runTranslateIfNeeded(context, true);
     await audio(context).then(images).then(captions).then(movie);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/pdf/handler.js

@@ -1,5 +1,5 @@
 import { images, pdf } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -8,4 +8,5 @@ export const handler = async (argv) => {
     await runTranslateIfNeeded(context);
     await images(context);
     await pdf(context, argv.pdf_mode, argv.pdf_size);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/tool/whisper/handler.js

@@ -51,40 +51,63 @@ export const handler = async (argv) => {
         GraphAILogger.error("Error: OPENAI_API_KEY environment variable is required");
         process.exit(1);
     }
-    try {
-        // Get audio duration using FFmpeg
-        const { duration: audioDuration } = await ffmpegGetMediaDuration(fullPath);
-        GraphAILogger.info(`Audio duration: ${audioDuration.toFixed(2)} seconds`);
-        const openai = new OpenAI({ apiKey });
-        const transcription = await openai.audio.transcriptions.create({
-            file: createReadStream(fullPath),
-            model: "whisper-1",
-            response_format: "verbose_json",
-            timestamp_granularities: ["word", "segment"],
-        });
-        if (transcription.segments) {
-            const starts = transcription.segments.map((segment) => segment.start);
-            starts[0] = 0;
-            starts.push(audioDuration);
-            // Create beats from transcription segments
-            const beats = transcription.segments.map((segment, index) => {
-                const duration = Math.round((starts[index + 1] - starts[index]) * 100) / 100;
-                return {
-                    text: segment.text,
-                    duration,
-                    /*
-                    image: {
-                      type: "textSlide",
-                      slide: {
-                        title: "Place Holder",
-                      },
-                    },
-                    */
-                };
+    // Each phase has its own try/catch so a failure points at the right
+    // subsystem instead of being collapsed into "Error transcribing audio"
+    // (same anti-pattern as #1451 in tts_gemini_agent.ts — an ffmpeg
+    // SIGABRT or a permission-denied write would otherwise read as an
+    // OpenAI-side failure).
+    // Phase 1 — ffmpeg: read the audio file's duration.
+    const audioDuration = await (async () => {
+        try {
+            const { duration } = await ffmpegGetMediaDuration(fullPath);
+            return duration;
+        }
+        catch (error) {
+            GraphAILogger.error("Error reading audio duration with ffmpeg:", error);
+            process.exit(1);
+        }
+    })();
+    GraphAILogger.info(`Audio duration: ${audioDuration.toFixed(2)} seconds`);
+    // Phase 2 — OpenAI: Whisper transcription API call.
+    const transcription = await (async () => {
+        try {
+            const openai = new OpenAI({ apiKey });
+            return await openai.audio.transcriptions.create({
+                file: createReadStream(fullPath),
+                model: "whisper-1",
+                response_format: "verbose_json",
+                timestamp_granularities: ["word", "segment"],
             });
-            // Create the script with the processed beats
-            const script = createMulmoScript(fullPath, beats);
-            // Save script to output directory
+        }
+        catch (error) {
+            GraphAILogger.error("Error calling OpenAI transcription API:", error);
+            process.exit(1);
+        }
+    })();
+    if (transcription.segments) {
+        const starts = transcription.segments.map((segment) => segment.start);
+        starts[0] = 0;
+        starts.push(audioDuration);
+        // Create beats from transcription segments
+        const beats = transcription.segments.map((segment, index) => {
+            const duration = Math.round((starts[index + 1] - starts[index]) * 100) / 100;
+            return {
+                text: segment.text,
+                duration,
+                /*
+                image: {
+                  type: "textSlide",
+                  slide: {
+                    title: "Place Holder",
+                  },
+                },
+                */
+            };
+        });
+        // Create the script with the processed beats
+        const script = createMulmoScript(fullPath, beats);
+        // Phase 3 — fs: write the generated script to disk.
+        try {
             const outputDir = "output";
             if (!existsSync(outputDir)) {
                 mkdirSync(outputDir, { recursive: true });
@@ -93,9 +116,9 @@ export const handler = async (argv) => {
             writeFileSync(outputPath, JSON.stringify(script, null, 2));
             GraphAILogger.info(`Script saved to: ${outputPath}`);
         }
-    }
-    catch (error) {
-        GraphAILogger.error("Error transcribing audio:", error);
-        process.exit(1);
+        catch (error) {
+            GraphAILogger.error("Error writing transcription output file:", error);
+            process.exit(1);
+        }
     }
 };

package/lib/cli/commands/translate/handler.js

@@ -1,9 +1,10 @@
 import { translate } from "../../../actions/index.js";
-import { initializeContext } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
         process.exit(1);
     }
     await translate(context);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/helpers.d.ts

@@ -1,6 +1,7 @@
 import type { CliArgs } from "../types/cli_types.js";
 import { FileObject, InitOptions, MulmoStudioContext } from "../types/index.js";
 export declare const runTranslateIfNeeded: (context: MulmoStudioContext, includeCaption?: boolean) => Promise<void>;
+export declare const dumpUsageIfRequested: (context: MulmoStudioContext) => void;
 export declare const setGraphAILogger: (verbose: boolean | undefined, logValues?: Record<string, unknown>) => void;
 export declare const getFileObject: (args: {
     basedir?: string;

package/lib/cli/helpers.js

@@ -14,6 +14,52 @@ export const runTranslateIfNeeded = async (context, includeCaption = false) => {
         await translate(context);
     }
 };
+const summarizeUsage = (context) => {
+    const snapshot = context.usageCollector?.snapshot() ?? [];
+    const groups = new Map();
+    for (const record of snapshot) {
+        const key = `${record.provider}:${record.model}`;
+        const group = groups.get(key) ?? {
+            provider: record.provider,
+            model: record.model,
+            records: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+            predictSec: 0,
+            inputChars: 0,
+        };
+        group.records += 1;
+        group.inputTokens += record.inputTokens ?? 0;
+        group.outputTokens += record.outputTokens ?? 0;
+        group.totalTokens += record.totalTokens ?? 0;
+        group.predictSec += record.predictSec ?? 0;
+        group.inputChars += record.inputChars ?? 0;
+        groups.set(key, group);
+    }
+    return { records: snapshot.length, byModel: Array.from(groups.values()), snapshot };
+};
+// Opt-in usage dump after a CLI action completes. Controlled by
+// MULMOCAST_DUMP_USAGE:
+//   - unset / empty → no-op (zero overhead)
+//   - "1" / "true" / "stdout" → print JSON to stdout via GraphAILogger.info
+//   - any other value → treated as a file path and the JSON is written there
+//
+// The API/billing layer reads context.usageCollector directly; this is for
+// local CLI verification only.
+export const dumpUsageIfRequested = (context) => {
+    const setting = process.env.MULMOCAST_DUMP_USAGE;
+    if (!setting)
+        return;
+    const payload = summarizeUsage(context);
+    const json = JSON.stringify(payload, null, 2);
+    if (setting === "1" || setting === "true" || setting === "stdout") {
+        GraphAILogger.info(json);
+        return;
+    }
+    fs.writeFileSync(setting, json, "utf-8");
+    GraphAILogger.info(`usage written to ${setting}`);
+};
 export const setGraphAILogger = (verbose, logValues) => {
     if (verbose) {
         if (logValues) {

package/lib/tools/create_mulmo_script_from_url.d.ts

@@ -1,3 +1,3 @@
 import { ScriptingParams } from "../types/index.js";
-export declare const createMulmoScriptFromUrl: ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model }: ScriptingParams) => Promise<void>;
-export declare const createMulmoScriptFromFile: (fileName: string, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose }: ScriptingParams) => Promise<void>;
+export declare const createMulmoScriptFromUrl: ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model, usageCollector }: ScriptingParams) => Promise<void>;
+export declare const createMulmoScriptFromFile: (fileName: string, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose, usageCollector }: ScriptingParams) => Promise<void>;

package/lib/tools/create_mulmo_script_from_url.js

@@ -15,6 +15,7 @@ import { mulmoScriptSchema, urlsSchema } from "../types/schema.js";
 import { cliLoadingPlugin } from "../utils/plugins.js";
 import { graphDataScriptFromUrlPrompt } from "../utils/prompt.js";
 import { llmPair, settings2GraphAIConfig } from "../utils/utils.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { readFileSync } from "fs";
 dotenv.config({ quiet: true });
 const vanillaAgents = agents.default ?? agents;
@@ -207,7 +208,7 @@ const graphDataText = {
         },
     },
 };
-export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model }) => {
+export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model, usageCollector }) => {
     mkdir(outDirPath);
     mkdir(cacheDirPath);
     const parsedUrls = urlsSchema.parse(urls);
@@ -239,6 +240,7 @@ export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath,
     graph.injectValue("llmModel", model);
     graph.injectValue("maxTokens", max_tokens);
     graph.registerCallback(cliLoadingPlugin({ nodeId: "mulmoScript", message: "Generating script..." }));
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = await graph.run();
     if (!result?.writeJSON?.path) {
         showErrorMessage("Script generation failed. Please try again.");
@@ -246,7 +248,7 @@ export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath,
     }
     writingMessage(result?.writeJSON?.path ?? "");
 };
-export const createMulmoScriptFromFile = async (fileName, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose }) => {
+export const createMulmoScriptFromFile = async (fileName, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose, usageCollector }) => {
     mkdir(outDirPath);
     mkdir(cacheDirPath);
     const filePath = path.resolve(process.cwd(), fileName);
@@ -272,6 +274,7 @@ export const createMulmoScriptFromFile = async (fileName, { templateName, outDir
     if (!verbose) {
         graph.registerCallback(cliLoadingPlugin({ nodeId: "mulmoScript", message: "Generating script..." }));
     }
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = await graph.run();
     if (!result?.writeJSON?.path) {
         showErrorMessage("Script generation failed. Please try again.");

package/lib/tools/create_mulmo_script_interactively.d.ts

@@ -1,2 +1,2 @@
 import { ScriptingParams } from "../types/index.js";
-export declare const createMulmoScriptInteractively: ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model }: ScriptingParams) => Promise<void>;
+export declare const createMulmoScriptInteractively: ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model, usageCollector, }: ScriptingParams) => Promise<void>;

package/lib/tools/create_mulmo_script_interactively.js

@@ -14,6 +14,7 @@ import { mulmoScriptSchema } from "../types/index.js";
 import { browserlessAgent } from "@graphai/browserless_agent";
 import validateSchemaAgent from "../agents/validate_schema_agent.js";
 import { llmPair, settings2GraphAIConfig } from "../utils/utils.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { interactiveClarificationPrompt, prefixPrompt } from "../utils/prompt.js";
 // import { cliLoadingPlugin } from "../utils/plugins.js";
 dotenv.config({ quiet: true });
@@ -199,7 +200,7 @@ const graphData = {
         },
     },
 };
-const scrapeWebContent = async (urls, cacheDirPath) => {
+const scrapeWebContent = async (urls, cacheDirPath, usageCollector) => {
     mkdir(cacheDirPath);
     GraphAILogger.info(`${agentHeader} Scraping ${urls.length} URLs...\n`);
     const browserlessCache = browserlessCacheGenerator(cacheDirPath);
@@ -212,16 +213,17 @@ const scrapeWebContent = async (urls, cacheDirPath) => {
     ];
     const graph = new GraphAI(graphDataForScraping, { ...vanillaAgents, openAIAgent, textInputAgent, fileWriteAgent, browserlessAgent }, { agentFilters });
     graph.injectValue("urls", urls);
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = (await graph.run());
     if (!result?.sourceText?.text) {
         return "";
     }
     return `\n\n${prefixPrompt}\n${result?.sourceText.text}`;
 };
-export const createMulmoScriptInteractively = async ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model }) => {
+export const createMulmoScriptInteractively = async ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model, usageCollector, }) => {
     mkdir(outDirPath);
     // if urls is not empty, scrape web content and reference it in the prompt
-    const webContentPrompt = urls.length > 0 ? await scrapeWebContent(urls, cacheDirPath) : "";
+    const webContentPrompt = urls.length > 0 ? await scrapeWebContent(urls, cacheDirPath, usageCollector) : "";
     const { agent, model, max_tokens } = llmPair(llm, llm_model);
     GraphAILogger.log({ agent, model, max_tokens });
     const agentFilters = [
@@ -255,6 +257,7 @@ export const createMulmoScriptInteractively = async ({ outDirPath, cacheDirPath,
             }
         }
     });
+    graph.registerCallback(createUsageCallback(usageCollector));
     // graph.registerCallback(cliLoadingPlugin({ nodeId: "reply", message: "Loading..." }));
     GraphAILogger.info(`${agentHeader} Hi! What topic would you like me to generate about?\n`);
     await graph.run();

package/lib/tools/deep_research.d.ts

@@ -1 +1,2 @@
-export declare const deepResearch: () => Promise<void>;
+import type { UsageCollectorAPI } from "../types/usage.js";
+export declare const deepResearch: (usageCollector?: UsageCollectorAPI) => Promise<void>;

package/lib/tools/deep_research.js

@@ -7,6 +7,7 @@ import * as agents from "@graphai/vanilla";
 import tavilySearchAgent from "../agents/tavily_agent.js";
 import { cliLoadingPlugin } from "../utils/plugins.js";
 import { searchQueryPrompt, reflectionPrompt, finalAnswerPrompt } from "../utils/prompt.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 dotenv.config({ quiet: true });
 const vanillaAgents = agents.default ?? agents;
 const agentHeader = "\x1b[34m● \x1b[0m\x1b[1mAgent\x1b[0m:\x1b[0m";
@@ -246,7 +247,7 @@ const graphData = {
         },
     },
 };
-export const deepResearch = async () => {
+export const deepResearch = async (usageCollector) => {
     const agentFilters = [
         {
             name: "consoleStreamDataAgentFilter",
@@ -260,6 +261,7 @@ export const deepResearch = async () => {
     graph.registerCallback(cliLoadingPlugin({ nodeId: "reflectionAgent", message: "Analyzing search results..." }));
     graph.registerCallback(cliLoadingPlugin({ nodeId: "tavilySearchAgent", message: "Searching..." }));
     graph.registerCallback(cliLoadingPlugin({ nodeId: "finalAnswer", message: "Generating final answer..." }));
+    graph.registerCallback(createUsageCallback(usageCollector));
     GraphAILogger.info(`${agentHeader} What would you like to know?\n`);
     await graph.run();
 };

package/lib/tools/story_to_script.d.ts

@@ -1,6 +1,7 @@
 import { MulmoStoryboard, StoryToScriptGenerateMode } from "../types/index.js";
 import type { LLM } from "../types/provider2agent.js";
-export declare const storyToScript: ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, }: {
+import type { UsageCollectorAPI } from "../types/usage.js";
+export declare const storyToScript: ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, usageCollector, }: {
     story: MulmoStoryboard;
     beatsPerScene: number;
     templateName: string;
@@ -9,4 +10,5 @@ export declare const storyToScript: ({ story, beatsPerScene, templateName, outdi
     llm?: LLM;
     llmModel?: string;
     generateMode: StoryToScriptGenerateMode;
+    usageCollector?: UsageCollectorAPI;
 }) => Promise<void>;

package/lib/tools/story_to_script.js

@@ -10,6 +10,7 @@ import { graphDataScriptGeneratePrompt, sceneToBeatsPrompt, storyToScriptInfoPro
 import { fileWriteAgent } from "@graphai/vanilla_node_agents";
 import validateSchemaAgent from "../agents/validate_schema_agent.js";
 import { llmPair, settings2GraphAIConfig } from "../utils/utils.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { storyToScriptGenerateMode } from "../types/const.js";
 import { cliLoadingPlugin } from "../utils/plugins.js";
 const vanillaAgents = agents.default ?? agents;
@@ -248,7 +249,7 @@ const generateScriptPrompt = async (template, beatsPerScene, story) => {
     const script = readScriptTemplateFile(template.scriptName);
     return storyToScriptPrompt(script, beatsPerScene, story);
 };
-export const storyToScript = async ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, }) => {
+export const storyToScript = async ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, usageCollector, }) => {
     const template = readAndParseJson(getPromptTemplateFilePath(templateName), mulmoPromptTemplateSchema);
     const { agent, model, max_tokens } = llmPair(llm, llmModel);
     const beatsPrompt = await generateBeatsPrompt(template, beatsPerScene, story);
@@ -271,6 +272,7 @@ export const storyToScript = async ({ story, beatsPerScene, templateName, outdir
     graph.injectValue("llmModel", model);
     graph.injectValue("maxTokens", max_tokens);
     graph.registerCallback(cliLoadingPlugin({ nodeId: "script", message: "Generating script..." }));
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = await graph.run();
     writingMessage(result?.writeJSON?.path ?? "");
 };

package/lib/types/agent.d.ts

@@ -10,10 +10,12 @@ export type OpenAIImageOptions = {
     quality?: OpenAIImageQuality;
     background?: "opaque" | "transparent" | "auto";
 };
+import type { AgentUsage } from "./usage.js";
 export type AgentBufferResult = {
     buffer?: Buffer;
     saved?: string;
     text?: string;
+    usage?: AgentUsage;
 };
 export type AgentPromptInputs = {
     prompt: string;

package/lib/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./type.js";
 export * from "./schema.js";
 export * from "./viewer.js";
+export * from "./usage.js";

package/lib/types/index.js

@@ -1,3 +1,4 @@
 export * from "./type.js";
 export * from "./schema.js";
 export * from "./viewer.js";
+export * from "./usage.js";

package/lib/types/type.d.ts

@@ -1,4 +1,5 @@
 import { type CallbackFunction } from "graphai";
+import type { UsageCollectorAPI } from "./usage.js";
 import { langSchema, localizedTextSchema, mulmoBeatSchema, mulmoScriptSchema, mulmoStudioSchema, mulmoStudioBeatSchema, mulmoStoryboardSchema, mulmoStoryboardSceneSchema, mulmoStudioMultiLingualSchema, mulmoStudioMultiLingualArraySchema, mulmoStudioMultiLingualDataSchema, mulmoStudioMultiLingualFileSchema, speakerDictionarySchema, speakerSchema, mulmoSpeechParamsSchema, mulmoImageParamsSchema, mulmoImageParamsImagesValueSchema, mulmoImageParamsImagesSchema, mulmoFillOptionSchema, mulmoTransitionSchema, mulmoVideoFilterSchema, mulmoMovieParamsSchema, mulmoSoundEffectParamsSchema, mulmoLipSyncParamsSchema, textSlideParamsSchema, speechOptionsSchema, speakerDataSchema, mulmoCanvasDimensionSchema, mulmoPromptTemplateSchema, mulmoPromptTemplateFileSchema, text2ImageProviderSchema, text2HtmlImageProviderSchema, text2MovieProviderSchema, text2SpeechProviderSchema, mulmoPresentationStyleSchema, multiLingualTextsSchema, mulmoImageAssetSchema, mulmoMermaidMediaSchema, mulmoTextSlideMediaSchema, mulmoMarkdownMediaSchema, mulmoImageMediaSchema, mulmoChartMediaSchema, mediaSourceSchema, mediaSourceMermaidSchema, backgroundImageSchema, backgroundImageSourceSchema, mulmoSessionStateSchema, mulmoOpenAIImageModelSchema, mulmoGoogleImageModelSchema, mulmoGoogleMovieModelSchema, mulmoReplicateMovieModelSchema, mulmoImagePromptMediaSchema, mulmoMovieMediaSchema, mulmoMoviePromptMediaSchema, markdownLayoutSchema, row2Schema, grid2x2Schema } from "./schema.js";
 import { pdf_modes, pdf_sizes, storyToScriptGenerateMode } from "./const.js";
 import type { LLM } from "./provider2agent.js";
@@ -68,6 +69,7 @@ export type MulmoStudioContext = {
     sessionState: MulmoSessionState;
     presentationStyle: MulmoPresentationStyle;
     multiLingual: MulmoStudioMultiLingualArray;
+    usageCollector?: UsageCollectorAPI;
 };
 export type ScriptingParams = {
     urls: string[];
@@ -78,6 +80,7 @@ export type ScriptingParams = {
     llm_model?: string;
     llm?: LLM;
     verbose?: boolean;
+    usageCollector?: UsageCollectorAPI;
 };
 export type ImageProcessorParams = {
     beat: MulmoBeat;

package/lib/types/usage.d.ts

@@ -0,0 +1,32 @@
+export type AgentUsage = {
+    provider: string;
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    predictSec?: number;
+    inputChars?: number;
+};
+export type UsageRecord = {
+    agent: string;
+    provider: string;
+    model: string;
+    beatIndex?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    predictSec?: number;
+    inputChars?: number;
+    cached: boolean;
+    retryAttempt?: number;
+    timestamp: string;
+};
+export type UsageCollectorAPI = {
+    add(record: Omit<UsageRecord, "timestamp"> & {
+        timestamp?: string;
+    }): void;
+    snapshot(): UsageRecord[];
+    merge(other: UsageCollectorAPI): void;
+    clear(): void;
+    readonly size: number;
+};

package/lib/types/usage.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/context.d.ts

@@ -1,4 +1,5 @@
 import type { MulmoStudioBeat, MulmoScript, MulmoPresentationStyle, MulmoStudioMultiLingual, FileObject } from "../types/type.js";
+import { UsageCollector } from "./usage_collector.js";
 export declare const silentMp3 = "https://github.com/receptron/mulmocast-cli/raw/refs/heads/main/assets/audio/silent300.mp3";
 export type MulmoErrorFormatter = (error: unknown) => string | null;
 export declare const setMulmoErrorFormatter: (formatter: MulmoErrorFormatter | null) => void;
@@ -5504,4 +5505,5 @@ export declare const initializeContextFromFiles: (files: FileObject, raiseError:
     force: boolean;
     backup: boolean;
     lang: string;
+    usageCollector: UsageCollector;
 } | null>;

package/lib/utils/context.js

@@ -4,6 +4,7 @@ import { beatId, multiLingualObjectToArray } from "./utils.js";
 import { mulmoStudioSchema, mulmoCaptionParamsSchema, mulmoPresentationStyleSchema } from "../types/schema.js";
 import { MulmoPresentationStyleMethods, MulmoScriptMethods, MulmoStudioMultiLingualMethod } from "../methods/index.js";
 import { loadMulmoConfig, mergeConfigWithScript } from "./mulmo_config.js";
+import { UsageCollector } from "./usage_collector.js";
 export const silentMp3 = "https://github.com/receptron/mulmocast-cli/raw/refs/heads/main/assets/audio/silent300.mp3";
 let mulmoErrorFormatter = null;
 export const setMulmoErrorFormatter = (formatter) => {
@@ -151,6 +152,7 @@ export const initializeContextFromFiles = async (files, raiseError, force, withB
             force: Boolean(force),
             backup: Boolean(withBackup),
             lang: targetLang ?? studio.script.lang, // This lang is target Language. studio.lang is default Language
+            usageCollector: new UsageCollector(),
         };
     }
     catch (error) {

package/lib/utils/filters.js

@@ -37,7 +37,7 @@ export const fileCacheAgentFilter = async (context, next) => {
         const output = (await next(context)) || undefined;
         const { buffer, text, saved } = output ?? {};
         if (saved) {
-            return true;
+            return output;
         }
         if (buffer) {
             writingMessage(file);
@@ -45,7 +45,7 @@ export const fileCacheAgentFilter = async (context, next) => {
             if (backup) {
                 await fsPromise.writeFile(getBackupFilePath(file), buffer);
             }
-            return true;
+            return output;
         }
         else if (text) {
             writingMessage(file);
@@ -53,10 +53,7 @@ export const fileCacheAgentFilter = async (context, next) => {
             if (backup) {
                 await fsPromise.writeFile(getBackupFilePath(file), text, "utf-8");
             }
-            return true;
-        }
-        else if (saved) {
-            return true;
+            return output;
         }
         GraphAILogger.log("no cache, no buffer: " + file);
         return false;