@stackfactor/agent-utils 1.0.0

package/dist/esm/langChain.js

@@ -0,0 +1,1236 @@
+import { ChatOpenAI } from "@langchain/openai";
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
+import { OpenAI } from "openai";
+import { GoogleGenAI } from "@google/genai";
+import constants from "./const.js";
+import { createAgent, tool } from "langchain";
+import errorHandlingHelper from "./errorHandling.js";
+import logger from "./logger.js";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+const NDJSON_SYSTEM_PROMPT = `
+You are a streaming JSON generator.
+
+You MUST output NDJSON (newline-delimited JSON).
+That means: ONE valid JSON object per line.
+
+Allowed event types:
+- "progress": short status update for the user
+- "final": final complete result
+
+Rules:
+- Output ONLY NDJSON lines (no markdown, no extra text).
+- Each line must be valid JSON.
+- "progress" must include: type, message, pct (with values between {minPercent} and {maxPercent})
+- "final" must include: type, content
+- End with EXACTLY ONE "final" event.
+- Do NOT reveal hidden chain-of-thought.
+
+CRITICAL - Escape special characters in ALL string values:
+- Newlines must be written as \\n (two characters: backslash + n)
+- Tabs must be written as \\t (two characters: backslash + t)
+- Carriage returns must be written as \\r (two characters: backslash + r)
+- Double quotes inside strings must be written as \\"
+- Backslashes must be written as \\\\
+This ensures valid JSON output.
+`.trim();
+const JSON_ESCAPE_INSTRUCTION = `
+CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
+- Newlines → \\n
+- Tabs → \\t  
+- Carriage returns → \\r
+- Double quotes inside strings → \\"
+- Backslashes → \\\\
+Do NOT include raw newlines, tabs, or unescaped quotes inside JSON string values.
+`.trim();
+const REPORT_PROGRESS_TOOL = `
+---
+### Report Progress to User
+BEFORE EACH task or step CALL the tool report_progress with:
+message: brief description of work you plan to do that makes sense for individuals in Learning and Development or Business Strategy roles. Don't include JSON word in any of the messages.
+percent: cumulative completion percentage with values between {minPercent}% and {maxPercent}%. Don't report percentage completion outside of this range.
+`;
+/**
+ * Converts a Zod validation error object into a human-readable multi-line string.
+ * Each failing field is described with its dot-notation path and a contextual message
+ * that depends on the Zod error code (e.g. `invalid_type`, `too_small`, `invalid_enum_value`).
+ * The output is prefixed with `"Schema validation failed:"` followed by a bulleted list.
+ * @param zodError - The Zod `ZodError` instance whose `errors` array will be formatted
+ * @returns A formatted string describing all validation failures
+ */
+const formatZodErrors = (zodError) => {
+    const errors = zodError.errors.map((err) => {
+        const path = err.path.length > 0 ? err.path.join(".") : "root";
+        // Provide more context based on error type
+        switch (err.code) {
+            case "invalid_type":
+                return `Field "${path}": Expected ${err.expected}, but received ${err.received}`;
+            case "invalid_literal":
+                return `Field "${path}": Expected literal value ${JSON.stringify(err.expected)}, but received ${JSON.stringify(err.received)}`;
+            case "unrecognized_keys":
+                return `Field "${path}": Unrecognized keys: ${err.keys.join(", ")}`;
+            case "invalid_union":
+                return `Field "${path}": Invalid union - none of the expected types matched`;
+            case "invalid_enum_value":
+                return `Field "${path}": Invalid enum value. Expected one of: ${err.options.join(", ")}`;
+            case "invalid_string":
+                return `Field "${path}": Invalid string format (${err.validation})`;
+            case "too_small":
+                return `Field "${path}": Value is too small (minimum: ${err.minimum})`;
+            case "too_big":
+                return `Field "${path}": Value is too large (maximum: ${err.maximum})`;
+            default:
+                return `Field "${path}": ${err.message}`;
+        }
+    });
+    return `Schema validation failed:\n  - ${errors.join("\n  - ")}`;
+};
+/**
+ * Validates a parsed JavaScript value against a Zod schema using `safeParse`. On
+ * success the validated (and potentially transformed) data is returned. On failure a
+ * formatted error is thrown with HTTP status `UNPROCESSABLE_ENTITY` and a message
+ * produced by `formatZodErrors`.
+ * @param data - The parsed value to validate (typically the result of `JSON.parse`)
+ * @param schema - A Zod schema object that exposes a `safeParse` method
+ * @returns The validated data as returned by Zod's `safeParse` result
+ */
+const validateWithSchema = (data, schema) => {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const formattedErrors = formatZodErrors(result.error);
+        throw errorHandlingHelper.create(constants.HTTP_CODES.UNPROCESSABLE_ENTITY, formattedErrors);
+    }
+    return result.data;
+};
+/**
+ * Determines whether a string looks like an HTML document rather than a JSON or plain-
+ * text response. Checks for common HTML start patterns such as `<!DOCTYPE`, `<html`,
+ * `<head`, `<body`, and `<?xml`. This is used to detect cases where an LLM API returns
+ * an error page or redirect instead of the expected content.
+ * @param text - The string to inspect
+ * @returns `true` if the string appears to be an HTML document, `false` otherwise
+ */
+const isHTMLResponse = (text) => {
+    if (!text || typeof text !== "string")
+        return false;
+    const trimmed = text.trim();
+    // Check for common HTML indicators
+    return (trimmed.startsWith("<!DOCTYPE") ||
+        trimmed.startsWith("<html") ||
+        trimmed.startsWith("<HTML") ||
+        trimmed.startsWith("<a ") ||
+        trimmed.startsWith("<div") ||
+        trimmed.startsWith("<p>") ||
+        trimmed.startsWith("<head") ||
+        trimmed.startsWith("<body") ||
+        trimmed.startsWith("<?xml") ||
+        /<html[\s>]/i.test(trimmed) ||
+        /<head[\s>]/i.test(trimmed) ||
+        /<body[\s>]/i.test(trimmed));
+};
+/**
+ * Attempts to extract and parse a JSON value from a raw LLM response string that may
+ * include markdown code fences, invalid escape sequences, control characters, or other
+ * extraneous formatting. Falls back through multiple strategies in order:
+ * 1. Direct parse after stripping fences and fixing `\'` escapes
+ * 2. Extract and parse the first `{...}` object block
+ * 3. Same as above after sanitising control characters and normalising line endings
+ * 4. Extract and parse the first `[...]` array block (with the same sanitisation)
+ * 5. Strip all non-printable characters and retry both object and array extraction
+ *
+ * Returns `null` if every strategy fails. Throws an error with `BAD_GATEWAY` if the
+ * response appears to be an HTML page (likely an API error or rate-limit redirect).
+ * @param text - The raw response string from the LLM
+ * @returns The parsed JavaScript value, or `null` if no JSON could be extracted
+ */
+const extractJSONFromResponse = (text) => {
+    if (!text || typeof text !== "string")
+        return null;
+    // Check for HTML responses (usually API errors or redirects)
+    if (isHTMLResponse(text)) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_GATEWAY, "LLM API returned HTML instead of JSON. This may indicate an API error, rate limit, or network issue. Please retry.");
+    }
+    // Remove markdown code blocks and fix invalid escape sequences
+    const cleaned = text
+        .replace(/```json\s*/gi, "")
+        .replace(/```\s*/g, "")
+        .replace(/\\'/g, "'") // Fix invalid \' escape (not valid in JSON)
+        .trim();
+    // Try parsing directly first
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch {
+        // Continue to fallback methods
+    }
+    // Try to find JSON object boundaries
+    const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+        try {
+            return JSON.parse(jsonMatch[0]);
+        }
+        catch {
+            // Try cleaning special characters
+            try {
+                const sanitized = jsonMatch[0]
+                    .replace(/[\u0000-\u001F\u007F-\u009F]/g, " ") // Remove control characters
+                    .replace(/\r\n/g, "\\n") // Normalize line endings
+                    .replace(/\r/g, "\\n")
+                    .replace(/\t/g, "\\t"); // Escape tabs
+                return JSON.parse(sanitized);
+            }
+            catch {
+                // Continue to next fallback
+            }
+        }
+    }
+    // Try to find JSON array boundaries
+    const arrayMatch = cleaned.match(/\[[\s\S]*\]/);
+    if (arrayMatch) {
+        try {
+            return JSON.parse(arrayMatch[0]);
+        }
+        catch {
+            try {
+                const sanitized = arrayMatch[0]
+                    .replace(/[\u0000-\u001F\u007F-\u009F]/g, " ")
+                    .replace(/\r\n/g, "\\n")
+                    .replace(/\r/g, "\\n")
+                    .replace(/\t/g, "\\t");
+                return JSON.parse(sanitized);
+            }
+            catch {
+                // Continue to next fallback
+            }
+        }
+    }
+    // Last resort: strip all non-printable except standard whitespace
+    try {
+        const stripped = cleaned.replace(/[^\x20-\x7E\n]/g, " ");
+        const finalMatch = stripped.match(/\{[\s\S]*\}/) || stripped.match(/\[[\s\S]*\]/);
+        if (finalMatch) {
+            return JSON.parse(finalMatch[0]);
+        }
+    }
+    catch {
+        // All attempts failed
+    }
+    return null;
+};
+/**
+ * Attempts to parse a JSON string without throwing. On failure it tries a second parse
+ * after sanitising Unicode control characters and normalising Windows-style line endings
+ * to `\n`. Returns `null` if both attempts fail, making it safe to call in stream
+ * processing loops where individual NDJSON lines may be malformed.
+ * @param line - A single line of text expected to contain a JSON value
+ * @returns The parsed value, or `null` if parsing failed after both attempts
+ */
+const safeJsonParse = (line) => {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        // Try with special character handling
+        try {
+            const sanitized = line
+                .replace(/[\u0000-\u001F\u007F-\u009F]/g, " ")
+                .replace(/\r\n/g, "\\n")
+                .replace(/\r/g, "\\n");
+            return JSON.parse(sanitized);
+        }
+        catch {
+            return null;
+        }
+    }
+};
+/**
+ * Creates a LangChain tool named `report_progress` that agents can call to emit
+ * progress updates during multi-step execution. When the tool is invoked by the agent,
+ * it clamps the reported percentage to the `[minPercent, maxPercent]` range, forwards
+ * the update to the `onProgress` callback, and returns a JSON acknowledgement string to
+ * the agent. If the callback throws, the tool returns a JSON error acknowledgement
+ * instead of propagating the exception.
+ * @param onProgress - Async or sync callback invoked with `{ progress, message }` on
+ *   each agent progress report
+ * @param minPercent - The lower bound of the percentage range the agent is allowed to
+ *   report; defaults to `0`
+ * @param maxPercent - The upper bound of the percentage range the agent is allowed to
+ *   report; defaults to `100`
+ * @returns A LangChain tool instance configured with a Zod schema for `{ stage, message, percent }`
+ */
+const getAIProgressTool = (onProgress, minPercent = 0, maxPercent = 100) => tool(async ({ stage, message, percent }) => {
+    try {
+        // Clamp percent to be within minPercent and maxPercent bounds
+        const rawPct = typeof percent === "number" ? percent : 0;
+        const clampedPct = Math.max(minPercent, Math.min(maxPercent, rawPct));
+        if (onProgress) {
+            await onProgress({
+                progress: clampedPct,
+                message: message,
+            });
+        }
+        return JSON.stringify({
+            acknowledged: true,
+            receivedAt: Date.now(),
+            stage,
+            percent: clampedPct,
+        });
+    }
+    catch (err) {
+        return JSON.stringify({
+            acknowledged: false,
+            error: err?.message || String(err),
+        });
+    }
+}, {
+    name: "report_progress",
+    description: `Mandatory after each phase: call with {stage, message, percent}. Percent must be between ${minPercent} and ${maxPercent} and monotonically increase.`,
+    schema: z.object({
+        stage: z.string().describe("Current stage of the process"),
+        message: z.string().describe("Progress message to display"),
+        percent: z
+            .number()
+            .min(minPercent)
+            .max(maxPercent)
+            .describe(`Progress percentage (${minPercent}-${maxPercent})`),
+    }),
+});
+/**
+ * Instantiates and returns the appropriate LangChain chat model based on the model
+ * name prefix. `claude-` maps to `ChatAnthropic`, `gemini-` maps to
+ * `ChatGoogleGenerativeAI`, and `gpt-` maps to `ChatOpenAI`. When a Zod `schema` is
+ * provided for a GPT model, native `response_format` with `json_schema` is configured
+ * on the OpenAI instance for structured output. Throws a `BAD_REQUEST` error for
+ * unrecognised model names.
+ * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
+ *   `"gemini-1.5-pro"`
+ * @param config - Configuration object containing API keys (`openAIAPIKey`,
+ *   `anthropicAPIKey`, `googleAPIKey`), optional `maxTokens`, and optional `temperature`
+ * @param schema - Optional Zod schema used to configure structured JSON output for
+ *   OpenAI GPT models via `response_format`; ignored for other providers
+ * @returns A configured LangChain chat model instance
+ */
+const getLLMModel = (modelName, config, schema = null) => {
+    const modelSettings = {
+        ...(config.temperature ? { temperature: config.temperature } : {}),
+    };
+    // Claude models (Anthropic)
+    if (modelName.startsWith("claude-")) {
+        return new ChatAnthropic({
+            apiKey: config.anthropicAPIKey,
+            maxTokens: config.maxTokens || 200000,
+            modelName: modelName,
+            ...modelSettings,
+        });
+    }
+    // Gemini models (Google)
+    else if (modelName.startsWith("gemini-")) {
+        return new ChatGoogleGenerativeAI({
+            apiKey: config.googleAPIKey,
+            maxOutputTokens: config.maxTokens || 200000,
+            model: modelName,
+            ...modelSettings,
+        });
+    }
+    // GPT models (OpenAI)
+    else if (modelName.startsWith("gpt-")) {
+        const openAISettings = {
+            apiKey: config.openAIAPIKey,
+            max_tokens: config.maxTokens || 200000,
+            modelName: modelName,
+            ...modelSettings,
+        };
+        // Use native response_format with JSON schema for structured output
+        if (schema) {
+            const jsonSchema = zodToJsonSchema(schema, { target: "openApi3" });
+            openAISettings.modelKwargs = {
+                response_format: {
+                    type: "json_schema",
+                    json_schema: {
+                        name: "response_schema",
+                        strict: true,
+                        schema: jsonSchema,
+                    },
+                },
+            };
+        }
+        return new ChatOpenAI(openAISettings);
+    }
+    throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, constants.ERROR.UNSUPPORTED_MODEL + ": " + modelName);
+};
+/**
+ * Constructs a LangChain agent configured with a specified model, system prompt, and
+ * set of tools. When an `onReportProgress` callback is provided, the NDJSON progress-
+ * reporting instruction block is appended to the system prompt and a `report_progress`
+ * tool is added to the tools array so the agent can emit incremental progress updates
+ * during execution. The percentage range for progress reporting is bounded by
+ * `minPercent` and `maxPercent`.
+ * @param name - A human-readable display name for the agent
+ * @param modelName - The LLM identifier passed to `getLLMModel` (e.g. `"gpt-4o"`)
+ * @param systemPrompt - The base system prompt describing the agent's role and behaviour
+ * @param tools - Array of LangChain tool instances the agent may invoke; defaults to
+ *   an empty array
+ * @param responseFormat - Optional structured response format descriptor passed to the
+ *   LangChain agent constructor
+ * @param config - Configuration object forwarded to `getLLMModel` (API keys, temperature, etc.)
+ * @param onReportProgress - Optional callback for progress updates; when provided the
+ *   progress tool is added and the system prompt is extended
+ * @param minPercent - Minimum progress percentage the agent is allowed to report;
+ *   defaults to `0`
+ * @param maxPercent - Maximum progress percentage the agent is allowed to report;
+ *   defaults to `100`
+ * @returns A configured LangChain agent instance ready to be run with `runAIAgent`
+ */
+const createAIAgent = (name, modelName, systemPrompt, tools = [], responseFormat, config, onReportProgress = null, minPercent = 0, maxPercent = 100) => {
+    //Prepare the complete system prompt with progress reporting instructions if needed
+    const completeSystemPrompt = `
+        ${systemPrompt}
+        ${onReportProgress
+        ? REPORT_PROGRESS_TOOL.replace(`{minPercent}`, minPercent).replace(`{maxPercent}`, maxPercent)
+        : ""}
+      `.trim();
+    // Create the agent with the specified model, system prompt, tools, and response format
+    const agent = createAgent({
+        name: name,
+        model: getLLMModel(modelName, config),
+        systemPrompt: completeSystemPrompt,
+        tools: onReportProgress
+            ? [...tools, getAIProgressTool(onReportProgress, minPercent, maxPercent)]
+            : tools,
+        ...(responseFormat ? { responseFormat: responseFormat } : {}),
+    });
+    return agent;
+};
+/**
+ * Executes a LangChain agent with a single user prompt and returns the raw agent
+ * response. When an `onProgress` callback is provided, LangChain callbacks are
+ * registered to forward `tool_start`, `tool_end` (including structured progress data
+ * from the `report_progress` tool), `agent_action`, and error events to the caller.
+ * Execution time is logged at the info level on completion.
+ * @param agent - A LangChain agent instance created by `createAIAgent`
+ * @param prompt - The user message string to send to the agent
+ * @param config - Configuration object; `config.recursionLimit` controls the maximum
+ *   number of agent steps (defaults to `25` when not specified)
+ * @param onProgress - Optional callback invoked with progress event objects throughout
+ *   agent execution
+ * @returns The raw response object returned by the agent's `invoke` method
+ */
+const runAIAgent = async (agent, prompt, config, onProgress = null) => {
+    const startTime = Date.now();
+    // Build callbacks for progress reporting if onProgress is provided
+    // const agentDisplayName = `${agent.options?.name} AI Agent`;
+    const callbacks = onProgress
+        ? [
+            {
+                handleToolStart: (toolInfo) => {
+                    if (toolInfo.name)
+                        onProgress({
+                            type: "tool_start",
+                            message: `Using "${toolInfo.name}" tool`,
+                            tool: toolInfo.name,
+                        });
+                },
+                handleToolEnd: (output) => {
+                    try {
+                        const progressInfo = extractJSONFromResponse(output.content);
+                        if (progressInfo &&
+                            typeof progressInfo === "object" &&
+                            progressInfo.percent &&
+                            progressInfo.message) {
+                            onProgress({
+                                progress: progressInfo.percent,
+                                message: progressInfo.message,
+                                output: typeof output === "string"
+                                    ? output
+                                    : JSON.stringify(output),
+                            });
+                        }
+                    }
+                    catch { }
+                },
+                handleAgentAction: (action) => {
+                    onProgress({
+                        type: "agent_action",
+                        message: action.log || `Calling "${action.tool}" action`,
+                        tool: action.tool,
+                        input: action.toolInput,
+                    });
+                },
+                // handleLLMStart: () => {
+                //   onProgress({
+                //     type: "llm_start",
+                //     message: `${agentDisplayName} is thinking`,
+                //   });
+                // },
+                // handleLLMEnd: () => {
+                //   onProgress({
+                //     type: "llm_end",
+                //     message: `${agentDisplayName} has completed processing`,
+                //   });
+                // },
+                handleChainError: (err) => {
+                    onProgress({
+                        type: "error",
+                        message: `Error: ${err?.message || String(err)}`,
+                    });
+                },
+            },
+        ]
+        : undefined;
+    const response = await agent.invoke({
+        messages: [{ role: "user", content: prompt }],
+    }, {
+        recursionLimit: config.recursionLimit || 25,
+        ...(callbacks ? { callbacks } : {}),
+    });
+    const endTime = Date.now();
+    const duration = endTime - startTime;
+    logger.log(null, logger.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
+    return response;
+};
+/**
+ * Guards that a response value is a non-empty string. If the response is a string it is
+ * returned unchanged. If not, a formatted error with `INTERNAL_SERVER_ERROR` and the
+ * `UNABLE_TO_GENERATE_CONTENT` message is thrown.
+ * @param response - The value to check, typically the raw content returned by an LLM
+ * @returns The response string when it is valid
+ */
+const throwErrorIfNotSuccessful = (response) => {
+    if (response && typeof response === "string") {
+        return response;
+    }
+    else {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, constants.ERROR.UNABLE_TO_GENERATE_CONTENT);
+    }
+};
+/**
+ * Sends a prompt to an LLM and returns the response, with support for streaming,
+ * agentic execution, progress reporting, JSON extraction, and Zod schema validation.
+ * The function operates in one of three modes depending on configuration:
+ *
+ * - **Agentic** (`config.agentic === true`): Creates a LangChain agent via
+ *   `createAIAgent`, runs it with `runAIAgent`, then extracts and validates the final
+ *   JSON from the last message in the agent's response.
+ * - **Streaming with progress** (`onProgressReport` provided, non-agentic): Uses the
+ *   LLM's stream API. For OpenAI GPT models with a schema, progress is reported based
+ *   on output character count. For other models, the response is expected in NDJSON
+ *   format with `progress` and `final` event lines.
+ * - **Non-streaming** (no `onProgressReport`, non-agentic): Directly invokes the LLM
+ *   and extracts JSON from the response.
+ *
+ * When `expectsJsonResponse` is `true`, JSON escape instructions are prepended to the
+ * system prompt and the parsed result is optionally validated against `schema`.
+ * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
+ *   `"gemini-1.5-pro"`
+ * @param config - Configuration object with API keys, `temperature`, optional `agentic`
+ *   flag, and optional `recursionLimit`
+ * @param prompt - The prompt to send; either a plain string (user message only) or an
+ *   array of `{ role, content }` message objects
+ * @param onProgressReport - Optional async callback invoked with `{ message, progress }`
+ *   objects throughout execution; enables streaming mode when provided
+ * @param minPercent - Minimum progress percentage to report; defaults to `0`
+ * @param maxPercent - Maximum progress percentage to report; defaults to `100`
+ * @param expectsJsonResponse - When `true` (the default), JSON escape instructions are
+ *   injected into the system prompt and the response is parsed as JSON
+ * @param schema - Optional Zod schema; when provided the parsed JSON response is
+ *   validated and an `UNPROCESSABLE_ENTITY` error is thrown on mismatch
+ * @param agentName - Display name for the agent in agentic mode; defaults to
+ *   `"StackFactor"`
+ * @param tools - Additional LangChain tools available to the agent in agentic mode;
+ *   defaults to an empty array
+ * @returns The LLM response as a JSON string (when `expectsJsonResponse` is `true`) or
+ *   as raw content (when `false`)
+ */
+const runPromptWithModel = async (modelName, config, prompt, onProgressReport, minPercent = 0, maxPercent = 100, expectsJsonResponse = true, schema = null, agentName = "StackFactor", tools = []) => {
+    // Agentic mode: use an agent with tools instead of simple LLM invocation
+    if (config.agentic === true) {
+        // Extract system prompt and user prompt from the prompt parameter
+        let systemPrompt = "";
+        let userPrompt = "";
+        if (typeof prompt === "string") {
+            userPrompt = prompt;
+        }
+        else if (Array.isArray(prompt)) {
+            // Extract system message if present
+            const systemMessage = prompt.find((msg) => msg.role === "system");
+            if (systemMessage) {
+                systemPrompt = systemMessage.content;
+            }
+            // Extract and combine user messages
+            userPrompt = prompt
+                .filter((msg) => msg.role === "user")
+                .map((msg) => msg.content)
+                .join("\n\n");
+        }
+        else {
+            throw new Error("Prompt must be a string or array of messages");
+        }
+        // Inject JSON formatting instructions when JSON response is expected
+        if (expectsJsonResponse) {
+            systemPrompt = systemPrompt
+                ? `${JSON_ESCAPE_INSTRUCTION}\n\n---\n\n${systemPrompt}`
+                : JSON_ESCAPE_INSTRUCTION;
+        }
+        // Build tools array, adding progress reporting tool if callback provided
+        // Create a shared progress tracker for both tool and callbacks
+        const progressTracker = { current: minPercent };
+        const agentTools = [...tools];
+        if (onProgressReport) {
+            // Wrap the progress callback to update the tracker
+            const trackingProgressCallback = (data) => {
+                if (typeof data.progress === "number") {
+                    progressTracker.current = data.progress;
+                }
+                onProgressReport(data);
+            };
+            agentTools.push(getAIProgressTool(trackingProgressCallback, minPercent, maxPercent));
+        }
+        // Create the agent with tools
+        const agent = createAIAgent(agentName, modelName, systemPrompt, agentTools, null, // responseFormat
+        config, null, // onReportProgress handled via tools array
+        minPercent, maxPercent);
+        // Run the agent with callback that includes current progress
+        const callbackWithProgress = onProgressReport
+            ? (data) => onProgressReport({ ...data, progress: progressTracker.current })
+            : null;
+        const response = await runAIAgent(agent, userPrompt, config, callbackWithProgress);
+        // Extract content from agent response
+        const messages = response?.messages || [];
+        if (messages.length === 0) {
+            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
+        }
+        const lastMessage = messages[messages.length - 1];
+        const rawContent = lastMessage?.content || "";
+        // If not expecting JSON, return raw content directly
+        if (!expectsJsonResponse) {
+            return rawContent;
+        }
+        // Process JSON response similar to non-agentic path
+        if (typeof rawContent === "string") {
+            const trimmed = rawContent.trim();
+            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (schema) {
+                        validateWithSchema(parsed, schema);
+                    }
+                    return JSON.stringify(parsed);
+                }
+                catch (parseError) {
+                    if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
+                        throw parseError;
+                    }
+                }
+            }
+            // Try to extract JSON from markdown or other wrapping
+            const extracted = extractJSONFromResponse(rawContent);
+            if (extracted) {
+                if (schema) {
+                    validateWithSchema(extracted, schema);
+                }
+                return JSON.stringify(extracted);
+            }
+        }
+        if (expectsJsonResponse) {
+            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `Agent returned non-JSON response when JSON was expected: ${rawContent.substring(0, 100)}...`);
+        }
+        return rawContent;
+    }
+    let messages;
+    if (typeof prompt === "string") {
+        messages = [{ role: "user", content: prompt }];
+    }
+    else if (Array.isArray(prompt)) {
+        messages = prompt;
+    }
+    else {
+        throw new Error("Prompt must be a string or array of messages");
+    }
+    if (onProgressReport) {
+        // Check if we can use native response_format (OpenAI with schema)
+        const useNativeStreamingSchema = expectsJsonResponse && schema && modelName.startsWith("gpt-");
+        if (useNativeStreamingSchema) {
+            // OpenAI with schema: use native response_format and stream with chunk-based progress
+            const llm = getLLMModel(modelName, config, schema);
+            const messagesToSend = messages.length > 0 && messages[0].role === "system"
+                ? messages
+                : [
+                    { role: "system", content: "Respond with valid JSON." },
+                    ...messages,
+                ];
+            let rawContent = "";
+            let lastProgressReport = 0;
+            const progressInterval = 1000; // Report progress every 1000 characters
+            const stream = await llm.stream(messagesToSend);
+            for await (const chunk of stream) {
+                const content = chunk?.content || chunk;
+                if (typeof content === "string") {
+                    rawContent += content;
+                    // Report progress based on content length
+                    if (rawContent.length - lastProgressReport >= progressInterval) {
+                        lastProgressReport = rawContent.length;
+                        const progress = Math.min(maxPercent - 5, // Reserve last 5% for completion
+                        minPercent +
+                            Math.floor((rawContent.length / 5000) * (maxPercent - minPercent)));
+                        await onProgressReport({
+                            message: "Generating content...",
+                            progress: progress,
+                        });
+                    }
+                }
+            }
+            // Report completion
+            await onProgressReport({
+                message: "Processing complete",
+                progress: maxPercent,
+            });
+            // Parse and validate the response
+            if (rawContent) {
+                try {
+                    const parsed = JSON.parse(rawContent.trim());
+                    if (schema) {
+                        validateWithSchema(parsed, schema);
+                    }
+                    return JSON.stringify(parsed);
+                }
+                catch (parseError) {
+                    if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
+                        throw parseError;
+                    }
+                    // Try to extract JSON
+                    const extracted = extractJSONFromResponse(rawContent);
+                    if (extracted) {
+                        if (schema) {
+                            validateWithSchema(extracted, schema);
+                        }
+                        return JSON.stringify(extracted);
+                    }
+                    if (expectsJsonResponse) {
+                        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${rawContent.substring(0, 100)}...`);
+                    }
+                    return rawContent;
+                }
+            }
+            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
+        }
+        // Non-OpenAI or no schema: use NDJSON streaming approach
+        const llm = getLLMModel(modelName, config);
+        let ndjsonSystemContent = NDJSON_SYSTEM_PROMPT.replace(`{minPercent}`, minPercent).replace(`{maxPercent}`, maxPercent);
+        // If schema is provided, include it in the system prompt
+        if (expectsJsonResponse && schema) {
+            const jsonSchema = zodToJsonSchema(schema, { target: "openApi3" });
+            ndjsonSystemContent += `\n\nThe "content" field in the "final" event MUST conform to this JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`;
+        }
+        let messagesWithNDJSON;
+        if (messages.length > 0 && messages[0].role === "system") {
+            messagesWithNDJSON = [
+                {
+                    role: "system",
+                    content: `${ndjsonSystemContent}\n\n---\n\n${messages[0].content}`,
+                },
+                ...messages.slice(1),
+            ];
+        }
+        else {
+            messagesWithNDJSON = [
+                {
+                    role: "system",
+                    content: ndjsonSystemContent,
+                },
+                ...messages,
+            ];
+        }
+        // Stream the response and parse NDJSON events
+        let buffer = "";
+        let finalContent = "";
+        let rawContent = "";
+        const stream = await llm.stream(messagesWithNDJSON);
+        for await (const chunk of stream) {
+            const content = chunk?.content || chunk;
+            if (typeof content === "string") {
+                buffer += content;
+                rawContent += content;
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    const trimmedLine = line.trim();
+                    if (!trimmedLine)
+                        continue;
+                    const parsed = safeJsonParse(trimmedLine);
+                    if (parsed) {
+                        if (parsed.type === "progress") {
+                            const clampedProgress = Math.max(minPercent, Math.min(maxPercent, parsed.pct));
+                            await onProgressReport({
+                                message: parsed.message,
+                                progress: clampedProgress,
+                            });
+                        }
+                        else if (parsed.type === "final") {
+                            if (parsed.content) {
+                                finalContent = parsed.content;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if (buffer.trim()) {
+            const parsed = safeJsonParse(buffer.trim());
+            if (parsed && parsed.type === "final" && parsed.content) {
+                finalContent = parsed.content;
+            }
+        }
+        if (finalContent) {
+            if (typeof finalContent === "object") {
+                if (expectsJsonResponse && schema) {
+                    validateWithSchema(finalContent, schema);
+                }
+                return JSON.stringify(finalContent);
+            }
+            if (typeof finalContent === "string") {
+                try {
+                    const parsed = JSON.parse(finalContent);
+                    if (expectsJsonResponse && schema) {
+                        validateWithSchema(parsed, schema);
+                    }
+                    return JSON.stringify(parsed);
+                }
+                catch (parseError) {
+                    if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
+                        throw parseError;
+                    }
+                    return finalContent;
+                }
+            }
+            return finalContent;
+        }
+        if (rawContent) {
+            const lines = rawContent.split("\n").filter((l) => l.trim());
+            let extractedContent = "";
+            for (const line of lines) {
+                const parsed = safeJsonParse(line.trim());
+                if (parsed && parsed.type === "final" && parsed.content) {
+                    extractedContent = parsed.content;
+                    break;
+                }
+            }
+            if (extractedContent) {
+                try {
+                    const parsed = JSON.parse(extractedContent);
+                    if (expectsJsonResponse && schema) {
+                        validateWithSchema(parsed, schema);
+                    }
+                    return JSON.stringify(parsed);
+                }
+                catch {
+                    return extractedContent;
+                }
+            }
+            const extracted = extractJSONFromResponse(rawContent);
+            if (extracted) {
+                if (expectsJsonResponse && schema) {
+                    validateWithSchema(extracted, schema);
+                }
+                return JSON.stringify(extracted);
+            }
+            if (expectsJsonResponse) {
+                throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${rawContent.substring(0, 100)}...`);
+            }
+            return rawContent;
+        }
+        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
+    }
+    else {
+        // Non-streaming mode: use native response_format for OpenAI when schema is provided
+        const useNativeSchema = expectsJsonResponse && schema && modelName.startsWith("gpt-");
+        const llm = getLLMModel(modelName, config, useNativeSchema ? schema : null);
+        // Add escape instruction to help LLM produce valid JSON (only if expecting JSON)
+        // For non-OpenAI models with schema, also include schema in prompt as fallback
+        let messagesToSend;
+        if (expectsJsonResponse) {
+            let systemContent = JSON_ESCAPE_INSTRUCTION;
+            // Include schema in prompt for non-OpenAI models (OpenAI uses native response_format)
+            if (schema && !modelName.startsWith("gpt-")) {
+                const jsonSchema = zodToJsonSchema(schema, { target: "openApi3" });
+                systemContent += `\n\nYour response MUST conform to this JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`;
+            }
+            if (messages.length > 0 && messages[0].role === "system") {
+                // Combine JSON escape instruction with user's system message
+                messagesToSend = [
+                    {
+                        role: "system",
+                        content: `${systemContent}\n\n---\n\n${messages[0].content}`,
+                    },
+                    ...messages.slice(1),
+                ];
+            }
+            else {
+                // Prepend JSON escape instruction as system message
+                messagesToSend = [
+                    {
+                        role: "system",
+                        content: systemContent,
+                    },
+                    ...messages,
+                ];
+            }
+        }
+        else {
+            messagesToSend = messages;
+        }
+        // Simply invoke without streaming
+        const response = await llm.invoke(messagesToSend);
+        const rawContent = response?.content || response;
+        // If not expecting JSON, return raw content directly
+        if (!expectsJsonResponse) {
+            return rawContent;
+        }
+        // If the response is already a string that looks like JSON, return it
+        // Otherwise, try to extract JSON from potential markdown wrapping
+        if (typeof rawContent === "string") {
+            const trimmed = rawContent.trim();
+            // Check if it's already clean JSON
+            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+                try {
+                    // Parse and re-stringify
+                    const parsed = JSON.parse(trimmed);
+                    // Validate against schema if provided
+                    if (schema) {
+                        validateWithSchema(parsed, schema);
+                    }
+                    return JSON.stringify(parsed);
+                }
+                catch (parseError) {
+                    // If it's a validation error, re-throw it
+                    if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
+                        throw parseError;
+                    }
+                    // Not valid JSON, try extraction
+                }
+            }
+            // Try to extract JSON from markdown or other wrapping
+            const extracted = extractJSONFromResponse(rawContent);
+            if (extracted) {
+                // Validate against schema if provided
+                if (schema) {
+                    validateWithSchema(extracted, schema);
+                }
+                return JSON.stringify(extracted);
+            }
+        }
+        // Return raw content as last resort - but throw if JSON was expected
+        if (expectsJsonResponse) {
+            const preview = typeof rawContent === "string" ? rawContent.substring(0, 100) : "";
+            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${preview}...`);
+        }
+        return rawContent;
+    }
+};
+/**
+ * Sends a conversational chat prompt to an LLM and returns a plain HTML response
+ * intended for end-user display. This function is purpose-built for the StackFactor
+ * Mentor chat feature: when the prompt is an array of messages, each `system` message
+ * is wrapped in an enhanced system prompt that instructs the model to answer only
+ * questions related to the provided topic, decline off-topic questions, and return
+ * results as simple HTML without markdown code-block notation. The call is delegated to
+ * `runPromptWithModel` with `expectsJsonResponse` set to `false`.
+ * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`
+ * @param config - Configuration object with API keys and optional `temperature`
+ * @param prompt - A plain string user message, or an array of `{ role, content }`
+ *   message objects; `system` messages have the topic-constraint wrapper applied
+ * @param onProgressReport - Optional callback for streaming progress updates passed
+ *   through to `runPromptWithModel`
+ * @returns The model's response as a raw HTML string
+ */
+const runChatPromptWithModel = (modelName, config, prompt, onProgressReport) => {
+    let messages = prompt;
+    // If prompt is an array, check for system message and enhance it
+    if (Array.isArray(prompt)) {
+        messages = prompt.map((msg) => {
+            if (msg.role === "system") {
+                return {
+                    ...msg,
+                    content: `You are StackFactor Mentor, an AI assistant that helps users by providing information related to the specified topic.
+          
+          ### Objective:
+          Respond to the user question considering just related to the selected topic and all previous interactions:
+          - If the question is unrelated decline to respond.
+          - Return the results as a simple HMTL but don't include notations for formatting blocks.
+          
+          ### TOPIC INFORMATION:\n
+          ${msg.content}
+          `,
+                };
+            }
+            return msg;
+        });
+    }
+    return runPromptWithModel(modelName, config, messages, onProgressReport, 0, 100, false);
+};
+/**
+ * Determines the image generation provider for a given model name based on its prefix.
+ * `dall-e-` and `gpt-image-` prefixes map to `"openai"`. `gemini-` and `imagen-`
+ * prefixes map to `"google"`. Returns `null` for any unrecognised prefix.
+ * @param modelName - The image model identifier to inspect
+ * @returns `"openai"`, `"google"`, or `null` when the provider cannot be determined
+ */
+const getImageModelProvider = (modelName) => {
+    // OpenAI models
+    if (modelName.startsWith("dall-e-") || modelName.startsWith("gpt-image-")) {
+        return "openai";
+    }
+    // Google models (Gemini and Imagen)
+    if (modelName.startsWith("gemini-") || modelName.startsWith("imagen-")) {
+        return "google";
+    }
+    return null;
+};
+/**
+ * Generates an image using an OpenAI image model (DALL-E 2, DALL-E 3, or GPT Image
+ * variants). Validates the `size` parameter against each model's allowed dimensions and
+ * enforces single-image (`n=1`) constraints for models that do not support batch
+ * generation. Returns a single image descriptor object when `n === 1`, or an object
+ * with an `images` array for batch requests. Each descriptor contains `url` or
+ * `b64_json` depending on `options.responseFormat`, plus a `revisedPrompt` field when
+ * provided by the API.
+ * @param modelName - The OpenAI image model identifier (e.g. `"dall-e-3"`,
+ *   `"gpt-image-1.5"`)
+ * @param config - Configuration object; must include `openAIAPIKey`
+ * @param prompt - The text prompt describing the image to generate
+ * @param options - Generation options including `size`, `style`, `responseFormat`
+ *   (`"url"` or `"b64_json"`), and `n` (number of images)
+ * @returns An object with `url`, `b64_json`, and `revisedPrompt` for a single image,
+ *   or `{ images: [...] }` for multiple images
+ */
+const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
+    const { size = "1024x1024", style = "vivid", responseFormat = "url", n = 1, } = options;
+    if (!config.openAIAPIKey) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "OpenAI API key is required for OpenAI image generation");
+    }
+    // Model-specific validations
+    const singleImageModels = ["dall-e-3", "gpt-image-1.5", "gpt-image-1-mini"];
+    if (singleImageModels.includes(modelName) && n > 1) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, `${modelName} only supports generating 1 image at a time (n=1)`);
+    }
+    // Validate size for each model
+    const validSizesDallE2 = ["256x256", "512x512", "1024x1024"];
+    const validSizesDallE3 = ["1024x1024", "1792x1024", "1024x1792"];
+    const validSizesGptImage = ["1024x1024", "1536x1024", "1024x1536", "auto"];
+    let validSizes;
+    if (modelName === "dall-e-2") {
+        validSizes = validSizesDallE2;
+    }
+    else if (modelName === "dall-e-3") {
+        validSizes = validSizesDallE3;
+    }
+    else {
+        // gpt-image models
+        validSizes = validSizesGptImage;
+    }
+    if (!validSizes.includes(size)) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, `Invalid size "${size}" for ${modelName}. Valid sizes: ${validSizes.join(", ")}`);
+    }
+    const openai = new OpenAI({ apiKey: config.openAIAPIKey });
+    const requestParams = {
+        model: modelName,
+        prompt: prompt,
+        n: n,
+        size: size,
+    };
+    // Add quality/style for models that support it
+    const supportsQualityStyle = [
+        "dall-e-3",
+        "gpt-image-1.5",
+        "gpt-image-1-mini",
+    ];
+    if (supportsQualityStyle.includes(modelName)) {
+        //requestParams.quality = quality;
+        if (modelName === "dall-e-3") {
+            requestParams.style = style;
+        }
+    }
+    const response = await openai.images.generate(requestParams);
+    // Format response based on number of images
+    if (n === 1) {
+        const imageData = response.data[0];
+        return {
+            url: responseFormat === "url" ? imageData.url : undefined,
+            b64_json: responseFormat === "b64_json" ? imageData.b64_json : undefined,
+            revisedPrompt: imageData.revised_prompt,
+        };
+    }
+    else {
+        return {
+            images: response.data.map((img) => ({
+                url: responseFormat === "url" ? img.url : undefined,
+                b64_json: responseFormat === "b64_json" ? img.b64_json : undefined,
+                revisedPrompt: img.revised_prompt,
+            })),
+        };
+    }
+};
+/**
+ * Generates an image using a Google AI model (Imagen or Gemini image variants) via the
+ * `@google/genai` SDK. Strips transparent-background requests from the prompt because
+ * Google models do not support alpha channels. Validates the `aspectRatio` against
+ * allowed values (`"1:1"`, `"3:4"`, `"4:3"`, `"9:16"`, `"16:9"`). Applies model-
+ * specific generation config: Imagen models receive `numberOfImages`, `aspectRatio`,
+ * `outputMimeType`, and optional `negativePrompt`; Gemini models receive `temperature`
+ * and `topP`. Safety settings are disabled for image generation. Throws an error if no
+ * images are returned.
+ * @param modelName - The Google model identifier (e.g. `"imagen-4.0-generate-001"`,
+ *   `"gemini-3.0-pro-image"`)
+ * @param config - Configuration object; must include `googleAPIKey`
+ * @param prompt - The text prompt describing the image to generate
+ * @param options - Generation options including `aspectRatio`, `numberOfImages`, and
+ *   optional `negativePrompt` (Imagen only)
+ * @returns A single image descriptor `{ b64_json, mimeType }` when one image is
+ *   requested, or `{ images: [...] }` for multiple images
+ */
+const generateImageWithGoogle = async (modelName, config, prompt, options) => {
+    const { aspectRatio = "1:1", numberOfImages = 1, negativePrompt = "", } = options;
+    if (!config.googleAPIKey) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Google API key is required for Google image generation");
+    }
+    // Remove transparent background requests as Google models don't support it
+    const cleanedPrompt = prompt
+        .replace(/\s*and transparent background\s*/gi, " ")
+        .replace(/\s*with transparent background\s*/gi, " ")
+        .replace(/\s*on transparent background\s*/gi, " ")
+        .replace(/\s*transparent background\s*/gi, " ")
+        .trim();
+    // Valid aspect ratios for Google Imagen/Gemini
+    const validAspectRatios = ["1:1", "3:4", "4:3", "9:16", "16:9"];
+    if (!validAspectRatios.includes(aspectRatio)) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, `Invalid aspectRatio "${aspectRatio}" for ${modelName}. Valid ratios: ${validAspectRatios.join(", ")}`);
+    }
+    // Initialize GoogleGenAI SDK
+    const ai = new GoogleGenAI({
+        apiKey: config.googleAPIKey,
+    });
+    // Determine the model type
+    const isImagenModel = modelName.startsWith("imagen-");
+    // Build generation config based on model type
+    const generationConfig = {
+        responseModalities: ["IMAGE", "TEXT"],
+        ...(isImagenModel
+            ? {
+                // Imagen-specific config
+                numberOfImages: numberOfImages,
+                aspectRatio: aspectRatio,
+                outputMimeType: "image/png",
+                ...(negativePrompt ? { negativePrompt: negativePrompt } : {}),
+            }
+            : {
+                // Gemini-specific config
+                temperature: 1,
+                topP: 0.95,
+            }),
+    };
+    // Safety settings (disable for image generation)
+    const safetySettings = [
+        { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "OFF" },
+        { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "OFF" },
+        { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "OFF" },
+        { category: "HARM_CATEGORY_HARASSMENT", threshold: "OFF" },
+    ];
+    const req = {
+        model: modelName,
+        contents: [
+            {
+                role: "user",
+                parts: [{ text: cleanedPrompt }],
+            },
+        ],
+        config: {
+            ...generationConfig,
+            safetySettings: safetySettings,
+        },
+    };
+    const response = await ai.models.generateContent(req);
+    // Extract images from response
+    const images = [];
+    const candidates = response.candidates || [];
+    for (const candidate of candidates) {
+        const parts = candidate.content?.parts || [];
+        for (const part of parts) {
+            if (part.inlineData) {
+                images.push({
+                    b64_json: part.inlineData.data,
+                    mimeType: part.inlineData.mimeType || "image/png",
+                });
+            }
+        }
+    }
+    if (images.length === 0) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `No images were generated by ${modelName}`);
+    }
+    if (numberOfImages === 1 || images.length === 1) {
+        return images[0];
+    }
+    return { images };
+};
+/**
+ * Top-level entry point for AI image generation. Routes the request to either
+ * `generateImageWithOpenAI` or `generateImageWithGoogle` based on the model name prefix
+ * detected by `getImageModelProvider`. Logs the total generation time on success.
+ * Re-throws already-formatted errors directly; wraps raw provider errors into a
+ * formatted `INTERNAL_SERVER_ERROR`.
+ *
+ * Supported OpenAI models: `"dall-e-2"`, `"dall-e-3"`, `"gpt-image-1.5"`,
+ *   `"gpt-image-1-mini"`.
+ * Supported Google models: `"imagen-4.0-generate-001"`,
+ *   `"imagen-4.0-fast-generate-001"`, `"imagen-4.0-ultra-generate-001"`,
+ *   `"gemini-3.0-pro-image"`, `"gemini-2.5-flash-image"`.
+ * @param modelName - The image model identifier; must start with a recognised prefix
+ * @param config - Configuration object with provider API keys (`openAIAPIKey` or
+ *   `googleAPIKey`)
+ * @param prompt - The text prompt describing the image to generate
+ * @param options - Provider-specific generation options (see `generateImageWithOpenAI`
+ *   and `generateImageWithGoogle` for full option sets); defaults to `{}`
+ * @returns The generated image data object returned by the provider-specific function
+ */
+const runPromptWithModelForImageGeneration = async (modelName, config, prompt, options = {}) => {
+    const provider = getImageModelProvider(modelName);
+    if (!provider) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, `Unable to determine provider for model: ${modelName}. Model name should start with 'gpt-image-', 'gemini-', or 'imagen-'.`);
+    }
+    const startTime = Date.now();
+    try {
+        let result;
+        if (provider === "openai") {
+            result = await generateImageWithOpenAI(modelName, config, prompt, options);
+        }
+        else if (provider === "google") {
+            result = await generateImageWithGoogle(modelName, config, prompt, options);
+        }
+        const endTime = Date.now();
+        const duration = endTime - startTime;
+        logger.log(null, logger.levels.info, `Image generation with "${modelName}" completed in ${Math.round(duration / 1000)} seconds.`);
+        return result;
+    }
+    catch (error) {
+        // Re-throw if already a formatted error
+        if (error?.code && error?.message) {
+            throw error;
+        }
+        // Handle provider-specific errors
+        if (error?.status || error?.code) {
+            const statusCode = error.status || constants.HTTP_CODES.INTERNAL_SERVER_ERROR;
+            const message = error.message || "Image generation failed";
+            throw errorHandlingHelper.create(statusCode, message);
+        }
+        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `Image generation failed: ${error?.message || String(error)}`);
+    }
+};
+export default {
+    createAIAgent,
+    runAIAgent,
+    runChatPromptWithModel,
+    runPromptWithModel,
+    runPromptWithModelForImageGeneration,
+    throwErrorIfNotSuccessful,
+};