mulmocast-preprocessor 0.2.0 → 0.3.0

package/README.md

@@ -14,6 +14,8 @@ npm install mulmocast-preprocessor
 - **Section filtering**: Extract beats by section
 - **Tag filtering**: Extract beats by tags
 - **Profile listing**: List available profiles with beat counts
+- **AI Summarization**: Generate summaries using LLM (OpenAI, Anthropic, Groq, Gemini)
+- **AI Query**: Ask questions about script content with interactive mode
 - **CLI tool**: Command-line interface for processing scripts
 
 ## CLI Usage
@@ -36,9 +38,23 @@ mulmocast-preprocessor script.json --profile summary --section chapter1
 
 # List available profiles
 mulmocast-preprocessor profiles script.json
+
+# Summarize script content
+mulmocast-preprocessor summarize script.json
+mulmocast-preprocessor summarize script.json --format markdown
+mulmocast-preprocessor summarize script.json -l ja  # Output in Japanese
+mulmocast-preprocessor summarize https://example.com/script.json  # From URL
+
+# Query script content
+mulmocast-preprocessor query script.json "What is the main topic?"
+mulmocast-preprocessor query script.json "登場人物は？" -l ja
+
+# Interactive query mode
+mulmocast-preprocessor query script.json -i
+mulmocast-preprocessor query script.json  # Omit question for interactive mode
 ```
 
-### CLI Options
+### CLI Options (process command)
 
 | Option | Alias | Description |
 |--------|-------|-------------|
@@ -49,6 +65,41 @@ mulmocast-preprocessor profiles script.json
 | `--help` | `-h` | Show help |
 | `--version` | `-v` | Show version |
 
+### CLI Options (summarize command)
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--provider` | | LLM provider: openai, anthropic, groq, gemini (default: openai) |
+| `--model` | `-m` | Model name |
+| `--format` | `-f` | Output format: text, markdown (default: text) |
+| `--lang` | `-l` | Output language (e.g., ja, en, zh) |
+| `--target-length` | | Target summary length in characters |
+| `--system-prompt` | | Custom system prompt |
+| `--verbose` | | Show detailed progress |
+| `--section` | `-s` | Filter by section name |
+| `--tags` | `-t` | Filter by tags (comma-separated) |
+
+### CLI Options (query command)
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--interactive` | `-i` | Start interactive query mode |
+| `--provider` | | LLM provider: openai, anthropic, groq, gemini (default: openai) |
+| `--model` | `-m` | Model name |
+| `--lang` | `-l` | Output language (e.g., ja, en, zh) |
+| `--system-prompt` | | Custom system prompt |
+| `--verbose` | | Show detailed progress |
+| `--section` | `-s` | Filter by section name |
+| `--tags` | `-t` | Filter by tags (comma-separated) |
+
+### Interactive Query Commands
+
+| Command | Description |
+|---------|-------------|
+| `/clear` | Clear conversation history |
+| `/history` | Show conversation history |
+| `/exit` | Exit interactive mode |
+
 ## Programmatic Usage
 
 ### Basic Example
@@ -132,6 +183,54 @@ Filter beats by section.
 
 Filter beats by tags (extracts beats that have any of the specified tags).
 
+### `summarizeScript(script, options)`
+
+Generate a summary of the script content using LLM.
+
+**Parameters:**
+- `script: ExtendedScript` - Input script
+- `options: SummarizeOptions` - Summarization options
+  - `provider?: LLMProvider` - LLM provider (default: "openai")
+  - `model?: string` - Model name
+  - `format?: "text" | "markdown"` - Output format
+  - `lang?: string` - Output language code
+  - `targetLengthChars?: number` - Target length
+  - `systemPrompt?: string` - Custom system prompt
+
+**Returns:** `Promise<SummarizeResult>` - Summary result with text and metadata
+
+### `queryScript(script, question, options)`
+
+Ask a question about the script content.
+
+**Parameters:**
+- `script: ExtendedScript` - Input script
+- `question: string` - Question to ask
+- `options: QueryOptions` - Query options (same as summarize)
+
+**Returns:** `Promise<QueryResult>` - Answer with question and metadata
+
+### `createInteractiveSession(script, options)`
+
+Create an interactive query session for follow-up questions.
+
+**Parameters:**
+- `script: ExtendedScript` - Input script
+- `options: QueryOptions` - Query options
+
+**Returns:** Session object with `sendInteractiveQuery()` method
+
+## Environment Variables
+
+For AI features (summarize, query), set the API key for your LLM provider:
+
+| Provider | Environment Variable |
+|----------|---------------------|
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| Gemini | `GEMINI_API_KEY` |
+
 ## Extended Schema
 
 ### ExtendedBeat

package/lib/cli/commands/query.d.ts

@@ -7,9 +7,10 @@ interface QueryCommandOptions {
     verbose?: boolean;
     section?: string;
     tags?: string[];
+    interactive?: boolean;
 }
 /**
  * Query command handler - outputs answer to stdout
  */
-export declare const queryCommand: (scriptPath: string, question: string, options: QueryCommandOptions) => Promise<void>;
+export declare const queryCommand: (scriptPath: string, question: string | undefined, options: QueryCommandOptions) => Promise<void>;
 export {};

package/lib/cli/commands/query.js

@@ -1,5 +1,7 @@
+import { createInterface } from "node:readline";
 import { GraphAILogger } from "graphai";
 import { queryScript } from "../../core/ai/command/query/index.js";
+import { createInteractiveSession, sendInteractiveQuery, sendInteractiveQueryWithFetch, clearHistory, getReferences, fetchReference, parseSuggestedFetch, removeSuggestFetchMarkers, } from "../../core/ai/command/query/interactive.js";
 import { loadScript } from "../utils.js";
 /**
  * Query command handler - outputs answer to stdout
@@ -7,6 +9,12 @@ import { loadScript } from "../utils.js";
 export const queryCommand = async (scriptPath, question, options) => {
     try {
         const script = await loadScript(scriptPath);
+        // Interactive mode
+        if (options.interactive || question === undefined) {
+            await runInteractiveMode(scriptPath, script, options);
+            return;
+        }
+        // Single query mode
         const result = await queryScript(script, question, {
             provider: options.provider ?? "openai",
             model: options.model,
@@ -29,3 +37,160 @@ export const queryCommand = async (scriptPath, question, options) => {
         process.exit(1);
     }
 };
+/**
+ * Format references for display
+ */
+const formatReferences = (references) => {
+    return references.map((ref, i) => `  ${i + 1}. [${ref.type || "web"}] ${ref.title || ref.url}`).join("\n");
+};
+/**
+ * Run interactive query mode
+ */
+const runInteractiveMode = async (scriptPath, script, options) => {
+    const { session, filteredScript, validatedOptions } = createInteractiveSession(script, {
+        provider: options.provider ?? "openai",
+        model: options.model,
+        lang: options.lang,
+        systemPrompt: options.systemPrompt,
+        verbose: options.verbose ?? false,
+        section: options.section,
+        tags: options.tags,
+    });
+    if (filteredScript.beats.length === 0) {
+        GraphAILogger.error("No content available to query.");
+        process.exit(1);
+    }
+    const references = getReferences(script);
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    GraphAILogger.info(`Interactive query mode for "${session.scriptTitle}" (${session.beatCount} beats)`);
+    GraphAILogger.info("Commands: /clear (clear history), /history (show history), /refs (show references), /fetch <url> (fetch URL), /exit (quit)");
+    if (references.length > 0) {
+        GraphAILogger.info(`Available references: ${references.length}`);
+    }
+    GraphAILogger.info("");
+    let lastSuggestedUrl = null;
+    const prompt = () => {
+        rl.question("You: ", async (input) => {
+            const trimmedInput = input.trim();
+            if (!trimmedInput) {
+                prompt();
+                return;
+            }
+            // Handle commands
+            if (trimmedInput === "/exit" || trimmedInput === "/quit") {
+                GraphAILogger.info("Goodbye!");
+                rl.close();
+                return;
+            }
+            if (trimmedInput === "/clear") {
+                clearHistory(session);
+                lastSuggestedUrl = null;
+                GraphAILogger.info("Conversation history cleared.\n");
+                prompt();
+                return;
+            }
+            if (trimmedInput === "/history") {
+                if (session.history.length === 0) {
+                    GraphAILogger.info("No conversation history.\n");
+                }
+                else {
+                    GraphAILogger.info("Conversation history:");
+                    session.history.forEach((msg) => {
+                        const prefix = msg.role === "user" ? "Q" : "A";
+                        GraphAILogger.info(`${prefix}: ${msg.content}`);
+                    });
+                    GraphAILogger.info("");
+                }
+                prompt();
+                return;
+            }
+            if (trimmedInput === "/refs" || trimmedInput === "/references") {
+                if (references.length === 0) {
+                    GraphAILogger.info("No references available.\n");
+                }
+                else {
+                    GraphAILogger.info("Available references:");
+                    GraphAILogger.info(formatReferences(references));
+                    GraphAILogger.info("");
+                }
+                prompt();
+                return;
+            }
+            // Handle /fetch command
+            if (trimmedInput.startsWith("/fetch")) {
+                const urlArg = trimmedInput.replace(/^\/fetch\s*/, "").trim();
+                const urlToFetch = urlArg || lastSuggestedUrl;
+                if (!urlToFetch) {
+                    GraphAILogger.info("Usage: /fetch <url> or /fetch (to fetch last suggested URL)\n");
+                    prompt();
+                    return;
+                }
+                GraphAILogger.info(`Fetching: ${urlToFetch}...`);
+                try {
+                    const fetchedContent = await fetchReference(urlToFetch, validatedOptions.verbose);
+                    if (fetchedContent.error) {
+                        GraphAILogger.error(`Fetch error: ${fetchedContent.error}\n`);
+                    }
+                    else {
+                        GraphAILogger.info(`Fetched ${fetchedContent.content.length} chars from ${fetchedContent.title || urlToFetch}`);
+                        GraphAILogger.info("Content loaded. Ask a question to use this reference.\n");
+                        // Store for next query
+                        session.fetchedContent = fetchedContent;
+                    }
+                }
+                catch (error) {
+                    if (error instanceof Error) {
+                        GraphAILogger.error(`Fetch error: ${error.message}\n`);
+                    }
+                    else {
+                        GraphAILogger.error("Unknown fetch error\n");
+                    }
+                }
+                prompt();
+                return;
+            }
+            // Send query
+            try {
+                let answer;
+                // If we have fetched content, use it
+                if (session.fetchedContent) {
+                    answer = await sendInteractiveQueryWithFetch(filteredScript, trimmedInput, session.fetchedContent, session, validatedOptions);
+                    // Clear fetched content after use
+                    session.fetchedContent = undefined;
+                }
+                else {
+                    answer = await sendInteractiveQuery(filteredScript, trimmedInput, session, validatedOptions);
+                }
+                // Check for suggested fetch URL
+                const suggestedUrl = parseSuggestedFetch(answer);
+                if (suggestedUrl) {
+                    lastSuggestedUrl = suggestedUrl;
+                    const cleanAnswer = removeSuggestFetchMarkers(answer);
+                    GraphAILogger.info(`\nAssistant: ${cleanAnswer}`);
+                    GraphAILogger.info(`\n(Suggested reference: ${suggestedUrl})`);
+                    GraphAILogger.info("Type /fetch to load this reference for more details.\n");
+                }
+                else {
+                    GraphAILogger.info(`\nAssistant: ${answer}\n`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    GraphAILogger.error(`Error: ${error.message}\n`);
+                }
+                else {
+                    GraphAILogger.error("Unknown error occurred\n");
+                }
+            }
+            prompt();
+        });
+    };
+    // Handle Ctrl+C
+    rl.on("close", () => {
+        process.exit(0);
+    });
+    prompt();
+};

package/lib/cli/index.js

@@ -111,16 +111,21 @@ yargs(hideBin(process.argv))
         tags,
     });
 })
-    .command("query <script> <question>", "Ask a question about the script content", (builder) => builder
+    .command("query <script> [question]", "Ask a question about the script content", (builder) => builder
     .positional("script", {
     describe: "Path or URL to MulmoScript JSON file",
     type: "string",
     demandOption: true,
 })
     .positional("question", {
-    describe: "Question to ask about the script",
+    describe: "Question to ask about the script (omit for interactive mode)",
     type: "string",
-    demandOption: true,
+})
+    .option("interactive", {
+    alias: "i",
+    describe: "Start interactive query mode",
+    type: "boolean",
+    default: false,
 })
     .option("provider", {
     describe: "LLM provider (openai, anthropic, groq, gemini)",
@@ -165,6 +170,7 @@ yargs(hideBin(process.argv))
         verbose: argv.verbose,
         section: argv.section,
         tags,
+        interactive: argv.interactive,
     });
 })
     .example("$0 script.json --profile summary -o summary.json", "Apply summary profile and save to file")
@@ -179,6 +185,8 @@ yargs(hideBin(process.argv))
     .example("$0 summarize https://example.com/script.json", "Summarize from URL")
     .example('$0 query script.json "What is the main topic?"', "Ask a question about the script")
     .example('$0 query script.json "登場人物は？" -l ja', "Query in Japanese")
+    .example("$0 query script.json -i", "Start interactive query mode")
+    .example("$0 query script.json", "Interactive mode (question omitted)")
     .help()
     .alias("h", "help")
     .version()

package/lib/core/ai/command/query/interactive.d.ts

@@ -0,0 +1,52 @@
+import type { ExtendedScript, Reference } from "../../../../types/index.js";
+import type { QueryOptions, InteractiveQuerySession, ConversationMessage } from "../../../../types/query.js";
+import { type FetchedContent } from "../../utils/fetcher.js";
+/**
+ * Create an interactive query session
+ */
+export declare const createInteractiveSession: (script: ExtendedScript, options?: Partial<QueryOptions>) => {
+    session: InteractiveQuerySession;
+    filteredScript: ExtendedScript;
+    validatedOptions: QueryOptions;
+};
+/**
+ * Send a question in an interactive session
+ */
+export declare const sendInteractiveQuery: (filteredScript: ExtendedScript, question: string, session: InteractiveQuerySession, options: QueryOptions) => Promise<string>;
+/**
+ * Clear conversation history
+ */
+export declare const clearHistory: (session: InteractiveQuerySession) => void;
+/**
+ * Get conversation history
+ */
+export declare const getHistory: (session: InteractiveQuerySession) => ConversationMessage[];
+/**
+ * Regex pattern for SUGGEST_FETCH marker (bounded quantifier to prevent ReDoS)
+ */
+export declare const SUGGEST_FETCH_PATTERN: RegExp;
+export declare const SUGGEST_FETCH_PATTERN_GLOBAL: RegExp;
+/**
+ * Parse suggested fetch URL from AI response
+ */
+export declare const parseSuggestedFetch: (response: string) => string | null;
+/**
+ * Remove SUGGEST_FETCH markers from response
+ */
+export declare const removeSuggestFetchMarkers: (response: string) => string;
+/**
+ * Get available references from script
+ */
+export declare const getReferences: (script: ExtendedScript) => Reference[];
+/**
+ * Fetch reference content by URL
+ */
+export declare const fetchReference: (url: string, verbose?: boolean) => Promise<FetchedContent>;
+/**
+ * Find matching reference for a query
+ */
+export declare const findReference: (script: ExtendedScript, query: string) => Reference | null;
+/**
+ * Send a question with fetched reference content
+ */
+export declare const sendInteractiveQueryWithFetch: (filteredScript: ExtendedScript, question: string, fetchedContent: FetchedContent, session: InteractiveQuerySession, options: QueryOptions) => Promise<string>;

package/lib/core/ai/command/query/interactive.js

@@ -0,0 +1,120 @@
+import { queryOptionsSchema } from "../../../../types/query.js";
+import { executeLLM, filterScript, getLanguageName } from "../../llm.js";
+import { buildInteractiveUserPrompt, getInteractiveSystemPrompt, DEFAULT_INTERACTIVE_SYSTEM_PROMPT_WITH_FETCH } from "./prompts.js";
+import { fetchUrlContent, findMatchingReference } from "../../utils/fetcher.js";
+/**
+ * Create an interactive query session
+ */
+export const createInteractiveSession = (script, options = {}) => {
+    const validatedOptions = queryOptionsSchema.parse(options);
+    const filteredScript = filterScript(script, validatedOptions);
+    const scriptTitle = script.title || "Untitled";
+    const session = {
+        scriptTitle,
+        beatCount: filteredScript.beats.length,
+        history: [],
+    };
+    return { session, filteredScript, validatedOptions };
+};
+/**
+ * Send a question in an interactive session
+ */
+export const sendInteractiveQuery = async (filteredScript, question, session, options) => {
+    if (filteredScript.beats.length === 0) {
+        return "No content available to answer the question.";
+    }
+    const systemPrompt = getInteractiveSystemPrompt(options);
+    const userPrompt = buildInteractiveUserPrompt(filteredScript, question, session.history);
+    const answer = await executeLLM(systemPrompt, userPrompt, options, options.verbose ? `Interactive query: ${question}` : undefined);
+    // Add to history
+    session.history.push({ role: "user", content: question });
+    session.history.push({ role: "assistant", content: answer });
+    return answer;
+};
+/**
+ * Clear conversation history
+ */
+export const clearHistory = (session) => {
+    session.history = [];
+};
+/**
+ * Get conversation history
+ */
+export const getHistory = (session) => {
+    return [...session.history];
+};
+/**
+ * Regex pattern for SUGGEST_FETCH marker (bounded quantifier to prevent ReDoS)
+ */
+export const SUGGEST_FETCH_PATTERN = /\[SUGGEST_FETCH:\s*([^\]]{1,2000})\]/;
+export const SUGGEST_FETCH_PATTERN_GLOBAL = /\[SUGGEST_FETCH:\s*[^\]]{1,2000}\]/g;
+/**
+ * Parse suggested fetch URL from AI response
+ */
+export const parseSuggestedFetch = (response) => {
+    const match = response.match(SUGGEST_FETCH_PATTERN);
+    return match ? match[1].trim() : null;
+};
+/**
+ * Remove SUGGEST_FETCH markers from response
+ */
+export const removeSuggestFetchMarkers = (response) => {
+    return response.replace(SUGGEST_FETCH_PATTERN_GLOBAL, "").trim();
+};
+/**
+ * Get available references from script
+ */
+export const getReferences = (script) => {
+    return script.scriptMeta?.references || [];
+};
+/**
+ * Fetch reference content by URL
+ */
+export const fetchReference = async (url, verbose = false) => {
+    return fetchUrlContent(url, 8000, verbose);
+};
+/**
+ * Find matching reference for a query
+ */
+export const findReference = (script, query) => {
+    const references = getReferences(script);
+    return findMatchingReference(references, query);
+};
+/**
+ * Send a question with fetched reference content
+ */
+export const sendInteractiveQueryWithFetch = async (filteredScript, question, fetchedContent, session, options) => {
+    if (filteredScript.beats.length === 0) {
+        return "No content available to answer the question.";
+    }
+    // Build system prompt for fetched content mode
+    let systemPrompt = DEFAULT_INTERACTIVE_SYSTEM_PROMPT_WITH_FETCH;
+    if (options.lang) {
+        const langName = getLanguageName(options.lang);
+        systemPrompt = `${systemPrompt}\n- IMPORTANT: Write the answer in ${langName}`;
+    }
+    // Build user prompt with fetched content
+    const baseUserPrompt = buildInteractiveUserPrompt(filteredScript, question, session.history);
+    // Insert fetched content before the question
+    const fetchedSection = [
+        "",
+        "---",
+        "Additional reference content fetched from URL:",
+        `URL: ${fetchedContent.url}`,
+        fetchedContent.title ? `Title: ${fetchedContent.title}` : "",
+        "",
+        fetchedContent.content,
+        "---",
+        "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    // Insert before "Current question:" or at the end
+    const insertPoint = baseUserPrompt.indexOf("Current question:");
+    const userPrompt = insertPoint >= 0 ? baseUserPrompt.slice(0, insertPoint) + fetchedSection + baseUserPrompt.slice(insertPoint) : baseUserPrompt + fetchedSection;
+    const answer = await executeLLM(systemPrompt, userPrompt, options, options.verbose ? `Interactive query with fetch: ${question}` : undefined);
+    // Add to history (include note about fetched content)
+    session.history.push({ role: "user", content: `${question} (with reference: ${fetchedContent.url})` });
+    session.history.push({ role: "assistant", content: answer });
+    return answer;
+};

package/lib/core/ai/command/query/prompts.d.ts

@@ -1,4 +1,4 @@
-import type { QueryOptions } from "../../../../types/query.js";
+import type { QueryOptions, ConversationMessage } from "../../../../types/query.js";
 import type { ExtendedScript } from "../../../../types/index.js";
 /**
  * Default system prompt for query
@@ -12,3 +12,19 @@ export declare const getSystemPrompt: (options: QueryOptions) => string;
  * Build user prompt from script and question
  */
 export declare const buildUserPrompt: (script: ExtendedScript, question: string) => string;
+/**
+ * Default system prompt for interactive query
+ */
+export declare const DEFAULT_INTERACTIVE_SYSTEM_PROMPT = "You are answering questions based on the content provided.\n- Answer based ONLY on the information in the provided content\n- If the answer cannot be found in the content, say so clearly\n- Be concise and direct in your answers\n- Do not make up information that is not in the content\n- You may reference previous conversation when answering follow-up questions\n- If references are available and the user asks for more details, mention which reference could provide more information\n- When you suggest fetching a reference for more details, include [SUGGEST_FETCH: <url>] in your response";
+/**
+ * Default system prompt for interactive query with fetched content
+ */
+export declare const DEFAULT_INTERACTIVE_SYSTEM_PROMPT_WITH_FETCH = "You are answering questions based on the content provided, including fetched reference content.\n- Answer based on both the main content and any fetched reference content\n- If the answer cannot be found, say so clearly\n- Be concise and direct in your answers\n- Do not make up information\n- You may reference previous conversation when answering follow-up questions\n- Prioritize information from fetched content when it's more detailed and relevant";
+/**
+ * Get system prompt for interactive mode
+ */
+export declare const getInteractiveSystemPrompt: (options: QueryOptions) => string;
+/**
+ * Build user prompt with conversation history for interactive mode
+ */
+export declare const buildInteractiveUserPrompt: (script: ExtendedScript, question: string, history: ConversationMessage[]) => string;

package/lib/core/ai/command/query/prompts.js

@@ -1,4 +1,4 @@
-import { getLanguageName } from "../../llm.js";
+import { getLanguageName, buildScriptContent } from "../../llm.js";
 /**
  * Default system prompt for query
  */
@@ -27,32 +27,73 @@ export const getSystemPrompt = (options) => {
  */
 export const buildUserPrompt = (script, question) => {
     const parts = [];
-    // Add script metadata
-    parts.push(`# Script: ${script.title}`);
-    parts.push(`Language: ${script.lang}`);
+    // Add common script content (title, language, sections with beats)
+    parts.push(buildScriptContent(script));
+    parts.push("---");
     parts.push("");
-    // Collect all text from beats
-    const sections = new Map();
-    script.beats.forEach((beat, index) => {
-        const text = beat.text || "";
-        if (!text.trim())
-            return;
-        const section = beat.meta?.section || "main";
-        if (!sections.has(section)) {
-            sections.set(section, []);
-        }
-        sections.get(section).push(`[${index}] ${text}`);
-    });
-    // Output by section
-    sections.forEach((texts, section) => {
-        parts.push(`## Section: ${section}`);
-        texts.forEach((t) => parts.push(t));
-        parts.push("");
-    });
+    parts.push(`Question: ${question}`);
     parts.push("");
+    parts.push("Answer:");
+    return parts.join("\n");
+};
+/**
+ * Default system prompt for interactive query
+ */
+export const DEFAULT_INTERACTIVE_SYSTEM_PROMPT = `You are answering questions based on the content provided.
+- Answer based ONLY on the information in the provided content
+- If the answer cannot be found in the content, say so clearly
+- Be concise and direct in your answers
+- Do not make up information that is not in the content
+- You may reference previous conversation when answering follow-up questions
+- If references are available and the user asks for more details, mention which reference could provide more information
+- When you suggest fetching a reference for more details, include [SUGGEST_FETCH: <url>] in your response`;
+/**
+ * Default system prompt for interactive query with fetched content
+ */
+export const DEFAULT_INTERACTIVE_SYSTEM_PROMPT_WITH_FETCH = `You are answering questions based on the content provided, including fetched reference content.
+- Answer based on both the main content and any fetched reference content
+- If the answer cannot be found, say so clearly
+- Be concise and direct in your answers
+- Do not make up information
+- You may reference previous conversation when answering follow-up questions
+- Prioritize information from fetched content when it's more detailed and relevant`;
+/**
+ * Get system prompt for interactive mode
+ */
+export const getInteractiveSystemPrompt = (options) => {
+    if (options.systemPrompt) {
+        return options.systemPrompt;
+    }
+    const basePrompt = DEFAULT_INTERACTIVE_SYSTEM_PROMPT;
+    if (options.lang) {
+        const langName = getLanguageName(options.lang);
+        return `${basePrompt}\n- IMPORTANT: Write the answer in ${langName}`;
+    }
+    return basePrompt;
+};
+/**
+ * Build user prompt with conversation history for interactive mode
+ */
+export const buildInteractiveUserPrompt = (script, question, history) => {
+    const parts = [];
+    // Add common script content (title, language, sections with beats)
+    parts.push(buildScriptContent(script));
     parts.push("---");
     parts.push("");
-    parts.push(`Question: ${question}`);
+    // Add conversation history if exists
+    if (history.length > 0) {
+        parts.push("Previous conversation:");
+        history.forEach((msg) => {
+            if (msg.role === "user") {
+                parts.push(`Q: ${msg.content}`);
+            }
+            else {
+                parts.push(`A: ${msg.content}`);
+            }
+        });
+        parts.push("");
+    }
+    parts.push(`Current question: ${question}`);
     parts.push("");
     parts.push("Answer:");
     return parts.join("\n");

package/lib/core/ai/command/summarize/prompts.js

@@ -1,4 +1,4 @@
-import { getLanguageName } from "../../llm.js";
+import { getLanguageName, buildScriptContent } from "../../llm.js";
 /**
  * Default system prompt for text summary
  */
@@ -23,28 +23,8 @@ export const DEFAULT_SYSTEM_PROMPT_MARKDOWN = `You are creating a summary based
  */
 export const buildUserPrompt = (script, options) => {
     const parts = [];
-    // Add script metadata
-    parts.push(`# Script: ${script.title}`);
-    parts.push(`Language: ${script.lang}`);
-    parts.push("");
-    // Collect all text from beats
-    const sections = new Map();
-    script.beats.forEach((beat, index) => {
-        const text = beat.text || "";
-        if (!text.trim())
-            return;
-        const section = beat.meta?.section || "main";
-        if (!sections.has(section)) {
-            sections.set(section, []);
-        }
-        sections.get(section).push(`[${index}] ${text}`);
-    });
-    // Output by section
-    sections.forEach((texts, section) => {
-        parts.push(`## Section: ${section}`);
-        texts.forEach((t) => parts.push(t));
-        parts.push("");
-    });
+    // Add common script content (title, language, sections with beats)
+    parts.push(buildScriptContent(script));
     // Add target length if specified
     if (options.targetLengthChars) {
         parts.push(`Target summary length: approximately ${options.targetLengthChars} characters`);

package/lib/core/ai/llm.d.ts

@@ -39,6 +39,22 @@ export declare const filterScript: (script: ExtendedScript, options: BaseLLMOpti
  * Get language name from code
  */
 export declare const getLanguageName: (langCode: string) => string;
+/**
+ * Build script content for user prompt (common part)
+ */
+export declare const buildScriptContent: (script: ExtendedScript) => string;
+/**
+ * Command execution result
+ */
+export interface CommandResult {
+    text: string;
+    scriptTitle: string;
+    beatCount: number;
+}
+/**
+ * Execute a command (summarize, query, etc.) with common logic
+ */
+export declare const executeCommand: <T extends BaseLLMOptions>(script: ExtendedScript, options: T, getSystemPrompt: (opts: T) => string, buildUserPrompt: (script: ExtendedScript) => string, verboseMessage: string) => Promise<CommandResult | null>;
 /**
  * Execute LLM call with GraphAI
  */

package/lib/core/ai/llm.js

@@ -103,6 +103,142 @@ export const getLanguageName = (langCode) => {
     };
     return langMap[langCode] || langCode;
 };
+/**
+ * Build beat content including metadata
+ */
+const buildBeatContent = (beat, index) => {
+    const lines = [];
+    // Main text
+    const text = beat.text || "";
+    if (!text.trim())
+        return "";
+    lines.push(`[${index}] ${text}`);
+    // Add metadata if available
+    const meta = beat.meta;
+    if (meta) {
+        // Tags for categorization
+        if (meta.tags && meta.tags.length > 0) {
+            lines.push(`  Tags: ${meta.tags.join(", ")}`);
+        }
+        // Context provides additional information not in the text
+        if (meta.context) {
+            lines.push(`  Context: ${meta.context}`);
+        }
+        // Keywords highlight important terms
+        if (meta.keywords && meta.keywords.length > 0) {
+            lines.push(`  Keywords: ${meta.keywords.join(", ")}`);
+        }
+        // Expected questions this beat can answer
+        if (meta.expectedQuestions && meta.expectedQuestions.length > 0) {
+            lines.push(`  Can answer: ${meta.expectedQuestions.join("; ")}`);
+        }
+    }
+    return lines.join("\n");
+};
+/**
+ * Build script-level metadata section
+ */
+const buildScriptMetaContent = (script) => {
+    const meta = script.scriptMeta;
+    if (!meta)
+        return "";
+    const lines = [];
+    // Background info
+    if (meta.background) {
+        lines.push(`Background: ${meta.background}`);
+    }
+    // Audience and prerequisites
+    if (meta.audience) {
+        lines.push(`Target audience: ${meta.audience}`);
+    }
+    if (meta.prerequisites && meta.prerequisites.length > 0) {
+        lines.push(`Prerequisites: ${meta.prerequisites.join(", ")}`);
+    }
+    // Goals
+    if (meta.goals && meta.goals.length > 0) {
+        lines.push(`Goals: ${meta.goals.join("; ")}`);
+    }
+    // Keywords
+    if (meta.keywords && meta.keywords.length > 0) {
+        lines.push(`Keywords: ${meta.keywords.join(", ")}`);
+    }
+    // References
+    if (meta.references && meta.references.length > 0) {
+        lines.push("References:");
+        meta.references.forEach((ref) => {
+            const title = ref.title || ref.url;
+            const desc = ref.description ? ` - ${ref.description}` : "";
+            lines.push(`  - [${ref.type || "web"}] ${title}: ${ref.url}${desc}`);
+        });
+    }
+    // FAQ
+    if (meta.faq && meta.faq.length > 0) {
+        lines.push("FAQ:");
+        meta.faq.forEach((faq) => {
+            lines.push(`  Q: ${faq.question}`);
+            lines.push(`  A: ${faq.answer}`);
+        });
+    }
+    // Author info
+    if (meta.author) {
+        lines.push(`Author: ${meta.author}`);
+    }
+    return lines.length > 0 ? lines.join("\n") : "";
+};
+/**
+ * Build script content for user prompt (common part)
+ */
+export const buildScriptContent = (script) => {
+    const parts = [];
+    // Add script title and language
+    parts.push(`# Script: ${script.title}`);
+    parts.push(`Language: ${script.lang}`);
+    parts.push("");
+    // Add script-level metadata
+    const scriptMetaContent = buildScriptMetaContent(script);
+    if (scriptMetaContent) {
+        parts.push("## About this content");
+        parts.push(scriptMetaContent);
+        parts.push("");
+    }
+    // Collect all content from beats grouped by section
+    const sections = new Map();
+    script.beats.forEach((beat, index) => {
+        const content = buildBeatContent(beat, index);
+        if (!content)
+            return;
+        const section = beat.meta?.section || "main";
+        if (!sections.has(section)) {
+            sections.set(section, []);
+        }
+        sections.get(section).push(content);
+    });
+    // Output by section
+    sections.forEach((contents, section) => {
+        parts.push(`## Section: ${section}`);
+        contents.forEach((c) => parts.push(c));
+        parts.push("");
+    });
+    return parts.join("\n");
+};
+/**
+ * Execute a command (summarize, query, etc.) with common logic
+ */
+export const executeCommand = async (script, options, getSystemPrompt, buildUserPrompt, verboseMessage) => {
+    const filteredScript = filterScript(script, options);
+    const scriptTitle = script.title || "Untitled";
+    if (filteredScript.beats.length === 0) {
+        return null;
+    }
+    const systemPrompt = getSystemPrompt(options);
+    const userPrompt = buildUserPrompt(filteredScript);
+    const text = await executeLLM(systemPrompt, userPrompt, options, verboseMessage);
+    return {
+        text,
+        scriptTitle,
+        beatCount: filteredScript.beats.length,
+    };
+};
 /**
  * Execute LLM call with GraphAI
  */

package/lib/core/ai/utils/fetcher.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fetched content result
+ */
+export interface FetchedContent {
+    url: string;
+    title: string | null;
+    content: string;
+    error?: string;
+}
+/**
+ * Fetch URL content and extract text
+ */
+export declare const fetchUrlContent: (url: string, maxLength?: number, verbose?: boolean) => Promise<FetchedContent>;
+/**
+ * Find matching reference URL from script metadata
+ */
+export declare const findMatchingReference: (references: Array<{
+    url: string;
+    title?: string;
+    description?: string;
+}> | undefined, query: string) => {
+    url: string;
+    title?: string;
+    description?: string;
+} | null;

package/lib/core/ai/utils/fetcher.js

@@ -0,0 +1,122 @@
+import { GraphAILogger } from "graphai";
+/**
+ * Strip HTML tags and extract text content
+ */
+const stripHtml = (html) => {
+    // Remove script and style elements
+    let text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "");
+    text = text.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "");
+    // Remove HTML comments
+    text = text.replace(/<!--[\s\S]*?-->/g, "");
+    // Replace common block elements with newlines
+    text = text.replace(/<\/(p|div|h[1-6]|li|tr|br)[^>]*>/gi, "\n");
+    // Remove all remaining HTML tags
+    // eslint-disable-next-line sonarjs/slow-regex -- standard HTML tag removal pattern, safe for typical HTML
+    text = text.replace(/<[^>]*>/g, " ");
+    // Decode common HTML entities
+    text = text.replace(/&nbsp;/g, " ");
+    text = text.replace(/&amp;/g, "&");
+    text = text.replace(/&lt;/g, "<");
+    text = text.replace(/&gt;/g, ">");
+    text = text.replace(/&quot;/g, '"');
+    text = text.replace(/&#39;/g, "'");
+    // Normalize whitespace
+    text = text.replace(/\s+/g, " ");
+    text = text.replace(/\n\s*\n/g, "\n\n");
+    return text.trim();
+};
+/**
+ * Extract title from HTML
+ */
+const extractTitle = (html) => {
+    const match = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+    return match ? match[1].trim() : null;
+};
+/**
+ * Fetch URL content and extract text
+ */
+export const fetchUrlContent = async (url, maxLength = 8000, verbose = false) => {
+    try {
+        if (verbose) {
+            GraphAILogger.info(`Fetching URL: ${url}`);
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30000);
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                "User-Agent": "Mozilla/5.0 (compatible; MulmoCast/1.0; +https://github.com/receptron/mulmocast)",
+                Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            return {
+                url,
+                title: null,
+                content: "",
+                error: `HTTP ${response.status}: ${response.statusText}`,
+            };
+        }
+        const contentType = response.headers.get("content-type") || "";
+        // Handle non-HTML content
+        if (!contentType.includes("text/html") && !contentType.includes("application/xhtml+xml")) {
+            if (contentType.includes("text/plain")) {
+                const text = await response.text();
+                return {
+                    url,
+                    title: null,
+                    content: text.substring(0, maxLength),
+                };
+            }
+            return {
+                url,
+                title: null,
+                content: "",
+                error: `Unsupported content type: ${contentType}`,
+            };
+        }
+        const html = await response.text();
+        const title = extractTitle(html);
+        const content = stripHtml(html);
+        // Truncate if needed
+        const truncatedContent = content.length > maxLength ? content.substring(0, maxLength) + "..." : content;
+        if (verbose) {
+            GraphAILogger.info(`Fetched ${content.length} chars from ${url}`);
+        }
+        return {
+            url,
+            title,
+            content: truncatedContent,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            url,
+            title: null,
+            content: "",
+            error: errorMessage,
+        };
+    }
+};
+/**
+ * Find matching reference URL from script metadata
+ */
+export const findMatchingReference = (references, query) => {
+    if (!references || references.length === 0) {
+        return null;
+    }
+    const lowerQuery = query.toLowerCase();
+    // Try to find a reference that matches keywords in the query
+    for (const ref of references) {
+        const refText = [ref.title, ref.description, ref.url].filter(Boolean).join(" ").toLowerCase();
+        // Simple keyword matching
+        const queryWords = lowerQuery.split(/\s+/).filter((w) => w.length > 2);
+        const matchScore = queryWords.filter((word) => refText.includes(word)).length;
+        if (matchScore >= 2 || (queryWords.length === 1 && matchScore === 1)) {
+            return ref;
+        }
+    }
+    return null;
+};

package/lib/index.d.ts

@@ -4,9 +4,12 @@ export { filterBySection, filterByTags, stripExtendedFields } from "./core/prepr
 export { listProfiles } from "./core/preprocessing/profiles.js";
 export { summarizeScript } from "./core/ai/command/summarize/index.js";
 export { queryScript } from "./core/ai/command/query/index.js";
-export type { BeatVariant, BeatMeta, ExtendedBeat, ExtendedScript, OutputProfile, ProcessOptions, ProfileInfo } from "./types/index.js";
+export { createInteractiveSession, sendInteractiveQuery, sendInteractiveQueryWithFetch, clearHistory, getHistory, getReferences, findReference, fetchReference, parseSuggestedFetch, removeSuggestFetchMarkers, } from "./core/ai/command/query/interactive.js";
+export { fetchUrlContent } from "./core/ai/utils/fetcher.js";
+export type { FetchedContent } from "./core/ai/utils/fetcher.js";
+export type { BeatVariant, BeatMeta, ExtendedBeat, ExtendedScript, OutputProfile, ProcessOptions, ProfileInfo, Reference, FAQ, ScriptMeta, } from "./types/index.js";
 export type { SummarizeOptions, SummarizeResult, LLMProvider, SummarizeFormat, ProviderConfig } from "./types/summarize.js";
-export type { QueryOptions, QueryResult } from "./types/query.js";
-export { beatVariantSchema, beatMetaSchema, extendedBeatSchema, extendedScriptSchema, outputProfileSchema } from "./types/index.js";
+export type { QueryOptions, QueryResult, ConversationMessage, InteractiveQuerySession } from "./types/query.js";
+export { beatVariantSchema, beatMetaSchema, extendedBeatSchema, extendedScriptSchema, outputProfileSchema, referenceSchema, faqSchema, scriptMetaSchema, } from "./types/index.js";
 export { summarizeOptionsSchema, llmProviderSchema, summarizeFormatSchema } from "./types/summarize.js";
 export { queryOptionsSchema } from "./types/query.js";

package/lib/index.js

@@ -6,7 +6,10 @@ export { listProfiles } from "./core/preprocessing/profiles.js";
 // AI API
 export { summarizeScript } from "./core/ai/command/summarize/index.js";
 export { queryScript } from "./core/ai/command/query/index.js";
+export { createInteractiveSession, sendInteractiveQuery, sendInteractiveQueryWithFetch, clearHistory, getHistory, getReferences, findReference, fetchReference, parseSuggestedFetch, removeSuggestFetchMarkers, } from "./core/ai/command/query/interactive.js";
+// Utilities
+export { fetchUrlContent } from "./core/ai/utils/fetcher.js";
 // Schemas (for validation)
-export { beatVariantSchema, beatMetaSchema, extendedBeatSchema, extendedScriptSchema, outputProfileSchema } from "./types/index.js";
+export { beatVariantSchema, beatMetaSchema, extendedBeatSchema, extendedScriptSchema, outputProfileSchema, referenceSchema, faqSchema, scriptMetaSchema, } from "./types/index.js";
 export { summarizeOptionsSchema, llmProviderSchema, summarizeFormatSchema } from "./types/summarize.js";
 export { queryOptionsSchema } from "./types/query.js";

package/lib/types/index.d.ts

@@ -860,6 +860,59 @@ export declare const outputProfileSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type OutputProfile = z.infer<typeof outputProfileSchema>;
+/**
+ * Reference - external resource reference
+ */
+export declare const referenceSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+        web: "web";
+        code: "code";
+        document: "document";
+        video: "video";
+    }>>;
+    url: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Reference = z.infer<typeof referenceSchema>;
+/**
+ * FAQ - frequently asked question
+ */
+export declare const faqSchema: z.ZodObject<{
+    question: z.ZodString;
+    answer: z.ZodString;
+    relatedBeats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type FAQ = z.infer<typeof faqSchema>;
+/**
+ * Script Meta - script-level metadata for AI features
+ */
+export declare const scriptMetaSchema: z.ZodObject<{
+    audience: z.ZodOptional<z.ZodString>;
+    prerequisites: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    goals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    background: z.ZodOptional<z.ZodString>;
+    faq: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        answer: z.ZodString;
+        relatedBeats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodEnum<{
+            web: "web";
+            code: "code";
+            document: "document";
+            video: "video";
+        }>>;
+        url: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    author: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ScriptMeta = z.infer<typeof scriptMetaSchema>;
 /**
  * Extended Script - script with variants, meta, and outputProfiles
  */
@@ -1924,6 +1977,31 @@ export declare const extendedScriptSchema: z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    scriptMeta: z.ZodOptional<z.ZodObject<{
+        audience: z.ZodOptional<z.ZodString>;
+        prerequisites: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        goals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        background: z.ZodOptional<z.ZodString>;
+        faq: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            question: z.ZodString;
+            answer: z.ZodString;
+            relatedBeats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodOptional<z.ZodEnum<{
+                web: "web";
+                code: "code";
+                document: "document";
+                video: "video";
+            }>>;
+            url: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        author: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strict>;
 export type ExtendedScript = z.infer<typeof extendedScriptSchema>;
 /**

package/lib/types/index.js

@@ -33,10 +33,47 @@ export const outputProfileSchema = z.object({
     name: z.string(),
     description: z.string().optional(),
 });
+/**
+ * Reference - external resource reference
+ */
+export const referenceSchema = z.object({
+    type: z.enum(["web", "code", "document", "video"]).optional(),
+    url: z.string(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+});
+/**
+ * FAQ - frequently asked question
+ */
+export const faqSchema = z.object({
+    question: z.string(),
+    answer: z.string(),
+    relatedBeats: z.array(z.string()).optional(),
+});
+/**
+ * Script Meta - script-level metadata for AI features
+ */
+export const scriptMetaSchema = z.object({
+    // Target audience and prerequisites
+    audience: z.string().optional(),
+    prerequisites: z.array(z.string()).optional(),
+    // Learning goals and background
+    goals: z.array(z.string()).optional(),
+    background: z.string().optional(),
+    // FAQ for quick Q&A matching
+    faq: z.array(faqSchema).optional(),
+    // Search and discovery
+    keywords: z.array(z.string()).optional(),
+    references: z.array(referenceSchema).optional(),
+    // Authoring info
+    author: z.string().optional(),
+    version: z.string().optional(),
+});
 /**
  * Extended Script - script with variants, meta, and outputProfiles
  */
 export const extendedScriptSchema = mulmoScriptSchema.extend({
     beats: z.array(extendedBeatSchema),
     outputProfiles: z.record(z.string(), outputProfileSchema).optional(),
+    scriptMeta: scriptMetaSchema.optional(),
 });

package/lib/types/query.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { FetchedContent } from "../core/ai/utils/fetcher.js";
 /**
  * Query Options - configuration for querying script content
  */
@@ -28,3 +29,19 @@ export interface QueryResult {
     scriptTitle: string;
     beatCount: number;
 }
+/**
+ * Conversation message for interactive query
+ */
+export interface ConversationMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+/**
+ * Interactive query session state
+ */
+export interface InteractiveQuerySession {
+    scriptTitle: string;
+    beatCount: number;
+    history: ConversationMessage[];
+    fetchedContent?: FetchedContent;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast-preprocessor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Preprocessor for MulmoScript",
   "type": "module",
   "main": "lib/index.js",