llm-exe 3.0.0 → 3.0.2

package/dist/index.mjs

@@ -464,6 +464,48 @@ function formatErrorList(values, options) {
   }
   return parts.join(", ");
 }
+function formatLlmExeErrorForLog(error) {
+  if (!error || typeof error !== "object") {
+    return formatErrorValue(error);
+  }
+  const e = error;
+  const name = typeof e.name === "string" && e.name ? e.name : "Error";
+  const message = typeof e.message === "string" ? e.message : "";
+  const code = typeof e.code === "string" ? e.code : void 0;
+  const category = typeof e.category === "string" ? e.category : void 0;
+  let header;
+  if (code) {
+    header = `${name} [${code}]: ${message}`;
+  } else if (category) {
+    header = `${name} [${category}]: ${message}`;
+  } else {
+    header = `${name}: ${message}`;
+  }
+  const chain = [];
+  let current = e.cause;
+  let depth = 0;
+  const seen = /* @__PURE__ */ new WeakSet();
+  while (current && depth < 5) {
+    if (typeof current === "object") {
+      if (seen.has(current)) {
+        chain.push("Caused by: [Circular]");
+        break;
+      }
+      seen.add(current);
+    }
+    const c = current;
+    const cName = typeof c.name === "string" && c.name ? c.name : "Error";
+    const cMsg = typeof c.message === "string" ? c.message : String(current);
+    const cCode = typeof c.code === "string" ? c.code : void 0;
+    chain.push(
+      cCode ? `Caused by: ${cName} [${cCode}]: ${cMsg}` : `Caused by: ${cName}: ${cMsg}`
+    );
+    current = c.cause;
+    depth++;
+  }
+  return chain.length > 0 ? `${header}
+${chain.join("\n")}` : header;
+}
 
 // src/errors/createLlmExeError.ts
 var DOCS_BASE_URL = "https://llm-exe.com";
@@ -985,7 +1027,9 @@ var BaseExecutor = class {
     return this;
   }
   on(eventName, fn) {
-    return this.setHooks({ [eventName]: fn });
+    return this.setHooks({
+      [eventName]: fn
+    });
   }
   off(eventName, fn) {
     return this.removeHook(eventName, fn);
@@ -1083,8 +1127,8 @@ var CoreExecutor = class extends BaseExecutor {
     __publicField(this, "_handler");
     this._handler = fn.handler.bind(null);
   }
-  async handler(_input) {
-    return this._handler.call(null, _input);
+  async handler(_input, _options, _context) {
+    return this._handler.call(null, _input, _context);
   }
 };
 
@@ -3236,6 +3280,7 @@ __export(utils_exports, {
   assert: () => assert,
   asyncCallWithTimeout: () => asyncCallWithTimeout,
   defineSchema: () => defineSchema,
+  escapeTemplateString: () => escapeTemplateString,
   filterObjectOnSchema: () => filterObjectOnSchema,
   guessProviderFromModel: () => guessProviderFromModel,
   importHelpers: () => importHelpers,
@@ -3308,6 +3353,12 @@ function importHelpers(_helpers) {
   return helpers;
 }
 
+// src/utils/modules/escapeTemplateString.ts
+function escapeTemplateString(input) {
+  if (typeof input !== "string") return input;
+  return input.replace(/\{\{/g, "\\{{");
+}
+
 // src/utils/modules/replaceTemplateStringAsync.ts
 async function replaceTemplateStringAsync(templateString, substitutions = {}, configuration = {
   helpers: [],
@@ -3973,9 +4024,53 @@ function OutputOpenAIChat(result, _config) {
   };
 }
 
+// src/llm/config/_utils/imageContent.ts
+function isImageUrlContentBlock(block) {
+  if (typeof block !== "object" || block === null) {
+    return false;
+  }
+  const imageUrl = block.image_url;
+  return typeof imageUrl === "object" && imageUrl !== null && typeof imageUrl.url === "string";
+}
+var DATA_URI_PATTERN = /^data:([^;,]+);base64,(.+)$/;
+function parseImageUrl(url, context) {
+  if (typeof url !== "string" || url.trim() === "") {
+    throw new LlmExeError("Image content block has an empty url", {
+      code: "prompt.invalid_messages",
+      context: {
+        ...context,
+        received: url,
+        expected: "an https URL or a data: URI",
+        resolution: "Set image_url.url to an https URL or a base64 data: URI (data:image/png;base64,...)."
+      }
+    });
+  }
+  if (url.startsWith("data:")) {
+    const match = url.match(DATA_URI_PATTERN);
+    if (!match) {
+      throw new LlmExeError("Malformed data: URI in image content block", {
+        code: "prompt.invalid_messages",
+        context: {
+          ...context,
+          received: `${url.slice(0, 48)}...`,
+          expected: "data:<media-type>;base64,<data>",
+          resolution: "Images must be base64-encoded with an explicit media type, e.g. data:image/png;base64,iVBOR..."
+        }
+      });
+    }
+    return { kind: "base64", mediaType: match[1], data: match[2] };
+  }
+  return { kind: "url", url };
+}
+
 // src/llm/config/openai/promptSanitizeMessageCallback.ts
 function openaiPromptMessageCallback(_message) {
   let message = { ..._message };
+  if (Array.isArray(message.content)) {
+    message.content = message.content.map(
+      (block) => isImageUrlContentBlock(block) && block.type !== "image_url" ? { ...block, type: "image_url" } : block
+    );
+  }
   if (message.role === "function") {
     message.role = "tool";
     message.tool_call_id = message.id;
@@ -4181,6 +4276,9 @@ var openai = {
   "openai.chat.v1": openAiChatV1,
   "openai.chat-mock.v1": openAiChatMockV1,
   // GPT-5 family
+  "openai.gpt-5.5": withDefaultModel(openAiChatV1, "gpt-5.5"),
+  "openai.gpt-5.4": withDefaultModel(openAiChatV1, "gpt-5.4"),
+  "openai.gpt-5.4-mini": withDefaultModel(openAiChatV1, "gpt-5.4-mini"),
   "openai.gpt-5.2": withDefaultModel(openAiChatV1, "gpt-5.2"),
   "openai.gpt-5-mini": withDefaultModel(openAiChatV1, "gpt-5-mini"),
   "openai.gpt-5-nano": withDefaultModel(openAiChatV1, "gpt-5-nano"),
@@ -4202,8 +4300,46 @@ var openai = {
 };
 
 // src/llm/config/anthropic/promptSanitizeMessageCallback.ts
-function anthropicPromptMessageCallback(_message) {
+function anthropicPromptMessageCallback(_message, options = {}) {
+  const { provider = "anthropic.chat", allowImageUrlSources = true } = options;
   let message = { ..._message };
+  if (Array.isArray(message.content)) {
+    message.content = message.content.map((block) => {
+      if (!isImageUrlContentBlock(block)) {
+        return block;
+      }
+      const parsed = parseImageUrl(block.image_url.url, {
+        operation: "anthropicPromptMessageCallback",
+        provider
+      });
+      if (parsed.kind === "base64") {
+        return {
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: parsed.mediaType,
+            data: parsed.data
+          }
+        };
+      }
+      if (!allowImageUrlSources) {
+        throw new LlmExeError("Image URLs are not supported by this provider", {
+          code: "prompt.invalid_messages",
+          context: {
+            operation: "anthropicPromptMessageCallback",
+            provider,
+            received: parsed.url,
+            expected: "a base64 data: URI",
+            resolution: "Bedrock does not fetch remote images. Base64-encode the image and pass it as a data: URI (data:image/png;base64,...)."
+          }
+        });
+      }
+      return {
+        type: "image",
+        source: { type: "url", url: parsed.url }
+      };
+    });
+  }
   if (message.role === "function") {
     message.role = "user";
     message.content = [
@@ -4249,10 +4385,11 @@ function mergeConsecutiveSameRole(messages) {
   }
   return merged;
 }
-function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
+function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj, _options = {}) {
+  const toAnthropicMessage = (m) => anthropicPromptMessageCallback(m, _options);
   if (typeof _messages === "string") {
     return [{ role: "user", content: _messages }].map(
-      anthropicPromptMessageCallback
+      toAnthropicMessage
     );
   }
   const [first, ...messages] = [
@@ -4262,7 +4399,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
     return [
       { role: "user", content: first.content },
       ...messages
-    ].map(anthropicPromptMessageCallback);
+    ].map(toAnthropicMessage);
   }
   if (first.role === "system" && messages.length > 0) {
     _outputObj.system = first.content;
@@ -4271,7 +4408,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
         return { ...m, role: "user" };
       }
       return m;
-    }).map(anthropicPromptMessageCallback);
+    }).map(toAnthropicMessage);
     return mergeConsecutiveSameRole(result2);
   }
   const result = [
@@ -4282,7 +4419,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
       }
       return m;
     })
-  ].map(anthropicPromptMessageCallback);
+  ].map(toAnthropicMessage);
   return mergeConsecutiveSameRole(result);
 }
 
@@ -4395,7 +4532,11 @@ var amazonAnthropicChatV1 = {
   mapBody: {
     prompt: {
       key: "messages",
-      transform: anthropicPromptSanitize
+      transform: (v, i, o) => anthropicPromptSanitize(v, i, o, {
+        provider: "amazon:anthropic.chat",
+        // Bedrock's invoke API only accepts base64 image sources
+        allowImageUrlSources: false
+      })
     },
     topP: {
       key: "top_p"
@@ -4451,6 +4592,21 @@ var amazonMetaChatV1 = {
         if (typeof messages === "string") {
           return messages;
         } else {
+          const hasImageContent = messages.some(
+            (message) => Array.isArray(message?.content) && message.content.some(isImageUrlContentBlock)
+          );
+          if (hasImageContent) {
+            throw new LlmExeError("Image content is not supported", {
+              code: "prompt.invalid_messages",
+              context: {
+                operation: "amazonMetaChatV1.prompt.transform",
+                provider: "amazon:meta.chat",
+                received: "a message with image content",
+                expected: "text-only messages",
+                resolution: "This model accepts a flattened text prompt and cannot receive images."
+              }
+            });
+          }
           return replaceTemplateString(`{{>DialogueHistory key='messages'}}`, {
             messages
           });
@@ -4478,7 +4634,11 @@ var bedrock = {
 
 // src/llm/config/anthropic/index.ts
 var ANTHROPIC_VERSION = "2023-06-01";
-var MODELS_REJECTING_SAMPLING_PARAMS = ["claude-opus-4-7", "claude-opus-4-8"];
+var MODELS_REJECTING_SAMPLING_PARAMS = [
+  "claude-opus-4-7",
+  "claude-opus-4-8",
+  "claude-fable-5"
+];
 var isClaude4x = (model) => /^claude-(opus|sonnet|haiku)-4-/.test(model);
 var dropIfModelRejectsSamplingParams = (v, body) => MODELS_REJECTING_SAMPLING_PARAMS.includes(body.model) ? void 0 : v;
 var topPTransform = (v, body) => {
@@ -4499,6 +4659,15 @@ var anthropicChatV1 = {
       required: [true, "maxTokens required"],
       default: 4096
     },
+    // Every key mapped in mapBody must also be declared here:
+    // stateFromOptions picks only declared option keys, so an undeclared
+    // key never reaches mapBody (see issue #661).
+    temperature: {},
+    topP: {},
+    topK: {},
+    stopSequences: {},
+    metadata: {},
+    serviceTier: {},
     anthropicApiKey: {
       default: getEnvironmentVariable("ANTHROPIC_API_KEY")
     }
@@ -4532,9 +4701,8 @@ var anthropicChatV1 = {
     stopSequences: {
       key: "stop_sequences"
     },
-    stream: {
-      key: "stream"
-    },
+    // No `stream` mapping: the request pipeline has no SSE support, so
+    // forwarding stream=true would return an unparseable response.
     metadata: {
       key: "metadata"
     },
@@ -4563,6 +4731,11 @@ var anthropicChatV1 = {
 };
 var anthropic = {
   "anthropic.chat.v1": anthropicChatV1,
+  // Claude Fable 5 models
+  "anthropic.claude-fable-5": withDefaultModel(
+    anthropicChatV1,
+    "claude-fable-5"
+  ),
   // Claude 4.8 models
   "anthropic.claude-opus-4-8": withDefaultModel(
     anthropicChatV1,
@@ -4596,10 +4769,9 @@ var anthropic = {
     config: withDefaultModel(anthropicChatV1, "claude-opus-4-6"),
     message: 'Shorthand "anthropic.claude-opus-4-6" is deprecated and may be removed in a future release.'
   }),
-  ...deprecateShorthand("anthropic.claude-opus-4-1", {
-    config: withDefaultModel(anthropicChatV1, "claude-opus-4-1-20250805"),
-    message: 'Shorthand "anthropic.claude-opus-4-1" is deprecated and may be removed in a future release.'
-  }),
+  // NOTE: "anthropic.claude-opus-4-1" (claude-opus-4-1-20250805) was removed —
+  // Anthropic retires that model on Aug 5, 2026. Migrate to
+  // anthropic.claude-opus-4-5/-6/-7/-8.
   ...deprecateShorthand("anthropic.claude-sonnet-4", {
     config: withDefaultModel(anthropicChatV1, "claude-sonnet-4-0"),
     message: 'Shorthand "anthropic.claude-sonnet-4" is deprecated and may be removed in a future release.'
@@ -4745,6 +4917,60 @@ function OutputOllamaChat(result, _config) {
   };
 }
 
+// src/llm/config/ollama/promptSanitize.ts
+function ollamaPromptSanitize(_messages) {
+  if (typeof _messages === "string") {
+    return [{ role: "user", content: _messages }];
+  }
+  return _messages.map((_message) => {
+    if (!Array.isArray(_message.content)) {
+      return _message;
+    }
+    const message = { ..._message };
+    const textParts = [];
+    const images = [];
+    for (const block of message.content) {
+      if (isImageUrlContentBlock(block)) {
+        const parsed = parseImageUrl(block.image_url.url, {
+          operation: "ollamaPromptSanitize",
+          provider: "ollama.chat"
+        });
+        if (parsed.kind === "url") {
+          throw new LlmExeError("Image URLs are not supported by ollama", {
+            code: "prompt.invalid_messages",
+            context: {
+              operation: "ollamaPromptSanitize",
+              provider: "ollama.chat",
+              received: parsed.url,
+              expected: "a base64 data: URI",
+              resolution: "Ollama does not fetch remote images. Base64-encode the image and pass it as a data: URI (data:image/png;base64,...)."
+            }
+          });
+        }
+        images.push(parsed.data);
+      } else if (typeof block?.text === "string") {
+        textParts.push(block.text);
+      } else {
+        throw new LlmExeError("Unsupported content block for ollama", {
+          code: "prompt.invalid_messages",
+          context: {
+            operation: "ollamaPromptSanitize",
+            provider: "ollama.chat",
+            received: block,
+            expected: "text or image_url content blocks",
+            resolution: "Ollama messages only support text and base64 images."
+          }
+        });
+      }
+    }
+    message.content = textParts.join("\n");
+    if (images.length > 0) {
+      message.images = images;
+    }
+    return message;
+  });
+}
+
 // src/llm/config/ollama/index.ts
 var ollamaChatV1 = {
   key: "ollama.chat.v1",
@@ -4762,12 +4988,7 @@ var ollamaChatV1 = {
   mapBody: {
     prompt: {
       key: "messages",
-      transform: (v) => {
-        if (typeof v === "string") {
-          return [{ role: "user", content: v }];
-        }
-        return v;
-      }
+      transform: (v) => ollamaPromptSanitize(v)
     },
     model: {
       key: "model"
@@ -4804,6 +5025,37 @@ var ollama = {
 };
 
 // src/llm/config/google/promptSanitizeMessageCallback.ts
+var GOOGLE_SUPPORTED_FILE_URI = /^(gs:\/\/|https:\/\/generativelanguage\.googleapis\.com\/)/;
+function googleGeminiContentBlockToPart(block) {
+  if (isImageUrlContentBlock(block)) {
+    const parsed = parseImageUrl(block.image_url.url, {
+      operation: "googleGeminiPromptMessageCallback",
+      provider: "google.chat"
+    });
+    if (parsed.kind === "base64") {
+      return {
+        inlineData: { mimeType: parsed.mediaType, data: parsed.data }
+      };
+    }
+    if (GOOGLE_SUPPORTED_FILE_URI.test(parsed.url)) {
+      return { fileData: { fileUri: parsed.url } };
+    }
+    throw new LlmExeError("Gemini cannot load images from arbitrary URLs", {
+      code: "prompt.invalid_messages",
+      context: {
+        operation: "googleGeminiPromptMessageCallback",
+        provider: "google.chat",
+        received: parsed.url,
+        expected: "a base64 data: URI, a Files API URI, or a gs:// URI",
+        resolution: "Pass the image as a data: URI (data:image/png;base64,...), or upload it with the Gemini Files API and pass the returned file URI."
+      }
+    });
+  }
+  if (typeof block?.text === "string") {
+    return { text: block.text };
+  }
+  return block;
+}
 function googleGeminiPromptMessageCallback(_message) {
   let message = { ..._message };
   const parts = [];
@@ -4817,6 +5069,9 @@ function googleGeminiPromptMessageCallback(_message) {
   if (typeof payload.content === "string" && message.role !== "function") {
     parts.push({ text: message.content });
   }
+  if (Array.isArray(payload.content) && message.role !== "function") {
+    parts.push(...payload.content.map(googleGeminiContentBlockToPart));
+  }
   if (message.role === "function") {
     role = "user";
     parts.push({
@@ -7633,10 +7888,12 @@ export {
   createState,
   createStateItem,
   defineSchema,
+  formatLlmExeErrorForLog,
   guards_exports as guards,
   isLlmExeError,
   registerHelpers,
   registerPartials,
+  serializeLlmExeError,
   useExecutors,
   useLlm,
   useLlmConfiguration,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-exe",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Simplify building LLM-powered apps with easy-to-use base components, supporting text and chat-based prompts with handlebars template engine, output parsers, and flexible function calling capabilities.",
   "keywords": [
     "ai",
@@ -48,6 +48,7 @@
     "predocs:build": "npm run build:docs-examples && bash scripts/generate-llms-txt.sh",
     "docs:dev": "eval $(cat docs/.env) && concurrently \"vitepress dev docs\" \"npm run build:watch:docs-examples\"",
     "docs:build": "eval $(cat docs/.env) && vitepress build docs",
+    "postdocs:build": "node docs/.vitepress/scripts/verify-docs-build.mjs",
     "docs:update-providers": "ts-node --transpile-only -r tsconfig-paths/register docs/.vitepress/scripts/updateProviders.ts",
     "lint": "eslint .",
     "format:check": "prettier --check \"src\"",

package/readme.md

@@ -14,7 +14,7 @@ A package that provides simplified base components to make building and maintain
 - Allow LLM's to call functions (or call other LLM executors).
 - Not very opinionated. You have control on how you use it.
 
-![llm-exe](https://assets.llm-exe.com/llm-exe-featured-2025.png)
+![llm-exe project logo](https://assets.llm-exe.com/llm-exe-featured-2025.png)
 
 See full docs here: [https://llm-exe.com](https://llm-exe.com)