llm-exe 3.0.0 → 3.1.0-beta.1

package/dist/index.js

@@ -67,10 +67,17 @@ __export(index_exports, {
   createState: () => createState,
   createStateItem: () => createStateItem,
   defineSchema: () => defineSchema,
+  executorFromConfig: () => executorFromConfig,
+  formatLlmExeErrorForLog: () => formatLlmExeErrorForLog,
   guards: () => guards_exports,
   isLlmExeError: () => isLlmExeError,
+  loadConfigFromUrl: () => loadConfigFromUrl,
+  loadExecutorConfig: () => loadExecutorConfig,
+  parseExecutorConfig: () => parseExecutorConfig,
   registerHelpers: () => registerHelpers,
   registerPartials: () => registerPartials,
+  runConfig: () => runConfig,
+  serializeLlmExeError: () => serializeLlmExeError,
   useExecutors: () => useExecutors,
   useLlm: () => useLlm,
   useLlmConfiguration: () => useLlmConfiguration,
@@ -179,6 +186,11 @@ var ALL_CODES = [
   "configuration.missing_env",
   "configuration.missing_option",
   "configuration.invalid_headers",
+  "configuration.parse_failed",
+  "configuration.invalid_config",
+  "configuration.file_not_found",
+  "configuration.file_read_failed",
+  "configuration.unsupported_format",
   "parser.invalid_type",
   "parser.invalid_input",
   "parser.parse_failed",
@@ -530,6 +542,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";
@@ -1051,7 +1105,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);
@@ -1149,8 +1205,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);
   }
 };
 
@@ -1607,9 +1663,9 @@ function validateParserSchema(schema, parsed) {
   if (!schema || !parsed || typeof parsed !== "object") {
     return null;
   }
-  const validate = (0, import_jsonschema.validate)(parsed, schema);
-  if (validate.errors.length) {
-    return validate.errors;
+  const validate2 = (0, import_jsonschema.validate)(parsed, schema);
+  if (validate2.errors.length) {
+    return validate2.errors;
   }
   return null;
 }
@@ -3302,6 +3358,7 @@ __export(utils_exports, {
   assert: () => assert,
   asyncCallWithTimeout: () => asyncCallWithTimeout,
   defineSchema: () => defineSchema,
+  escapeTemplateString: () => escapeTemplateString,
   filterObjectOnSchema: () => filterObjectOnSchema,
   guessProviderFromModel: () => guessProviderFromModel,
   importHelpers: () => importHelpers,
@@ -3374,6 +3431,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: [],
@@ -7669,6 +7732,361 @@ function createDialogue(name) {
 function createStateItem(name, defaultValue) {
   return new DefaultStateItem(name, defaultValue);
 }
+
+// src/config/schema.ts
+var import_jsonschema2 = require("jsonschema");
+
+// src/config/errors.ts
+var DOCS_PATH = "/config";
+function configParseFailedError(context, options) {
+  return createLlmExeError(
+    {
+      code: "configuration.parse_failed",
+      message: (ctx) => `Failed to parse ${ctx.format ?? "config"} configuration${typeof ctx.position === "number" ? ` at position ${ctx.position}` : ""}.`,
+      resolution: "Check the file is valid for its format (JSON/YAML/markdown frontmatter). Pass an explicit `format` if auto-detection is guessing wrong.",
+      docsPath: DOCS_PATH
+    },
+    context,
+    options
+  );
+}
+function configInvalidError(context, options) {
+  return createLlmExeError(
+    {
+      code: "configuration.invalid_config",
+      message: (ctx) => {
+        if (ctx.schemaErrors?.length) {
+          return `Invalid executor config: ${ctx.schemaErrors.join("; ")}.`;
+        }
+        if (ctx.field) {
+          return `Invalid executor config at \`${ctx.field}\`: expected ${String(
+            ctx.expected
+          )}.`;
+        }
+        return "Invalid executor config.";
+      },
+      resolution: "Fix the listed fields. `provider` and `message` are required; `provider` must be a known useLlm key.",
+      docsPath: DOCS_PATH
+    },
+    context,
+    options
+  );
+}
+
+// src/config/schema.ts
+var executorConfigSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  type: "object",
+  required: ["provider", "message"],
+  additionalProperties: false,
+  properties: {
+    provider: { type: "string", minLength: 1 },
+    model: { type: "string" },
+    system: { type: "string" },
+    message: { type: "string", minLength: 1 },
+    parser: { type: "string", minLength: 1 },
+    parserOptions: { type: "object" },
+    llmOptions: { type: "object" },
+    executorOptions: { type: "object" },
+    data: { type: "object" }
+  }
+};
+function validate(input) {
+  const result = (0, import_jsonschema2.validate)(input, executorConfigSchema);
+  if (!result.valid) {
+    const schemaErrors = result.errors.map((error) => {
+      const field = error.property.replace(/^instance\.?/, "") || "(root)";
+      return `${field} ${error.message}`;
+    });
+    throw configInvalidError({
+      schemaErrors,
+      field: result.errors[0]?.property.replace(/^instance\.?/, ""),
+      expected: result.errors[0]?.argument,
+      received: input
+    });
+  }
+  return input;
+}
+
+// src/config/normalize.ts
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var PATCH_REPLACE_FIELDS = [
+  "model",
+  "provider",
+  "parser",
+  "parserOptions",
+  "llmOptions",
+  "executorOptions",
+  "system",
+  "message"
+];
+function isPlainObject3(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function deepMerge(base, override) {
+  const out = {};
+  for (const key of Object.keys(base)) {
+    if (FORBIDDEN_KEYS.has(key)) continue;
+    out[key] = base[key];
+  }
+  for (const key of Object.keys(override)) {
+    if (FORBIDDEN_KEYS.has(key)) continue;
+    const next = override[key];
+    if (next === void 0) continue;
+    const prev = out[key];
+    if (isPlainObject3(next)) {
+      out[key] = deepMerge(isPlainObject3(prev) ? prev : {}, next);
+    } else {
+      out[key] = next;
+    }
+  }
+  return out;
+}
+function mergeData(base, override) {
+  if (override === void 0) return base;
+  if (base === void 0) return deepMerge({}, override);
+  return deepMerge(base, override);
+}
+function normalizeConfig(raw, patch) {
+  if (!isPlainObject3(raw)) {
+    throw configInvalidError({
+      field: "(root)",
+      expected: "object",
+      received: raw
+    });
+  }
+  const merged = { ...raw };
+  if ("output" in merged) {
+    if (merged.parser === void 0 && merged.output !== void 0) {
+      merged.parser = merged.output;
+    }
+    delete merged.output;
+  }
+  if (patch) {
+    for (const field of PATCH_REPLACE_FIELDS) {
+      if (patch[field] !== void 0) {
+        merged[field] = patch[field];
+      }
+    }
+    if (patch.data !== void 0) {
+      merged.data = mergeData(
+        isPlainObject3(merged.data) ? merged.data : void 0,
+        patch.data
+      );
+    }
+  }
+  if (merged.parser === void 0) {
+    merged.parser = "string";
+  }
+  const config = validate(merged);
+  if (!(config.provider in configs)) {
+    throw configInvalidError({
+      field: "provider",
+      received: config.provider,
+      availableProviders: Object.keys(configs)
+    });
+  }
+  if (config.message.trim() === "") {
+    throw configInvalidError({
+      field: "message",
+      expected: "non-empty string",
+      received: config.message
+    });
+  }
+  return config;
+}
+
+// src/config/assemble.ts
+function loadExecutorConfig(object, patch) {
+  return normalizeConfig(object, patch);
+}
+function executorFromConfig(config, createOptions) {
+  const llmOptions = {
+    ...config.llmOptions,
+    ...config.model ? { model: config.model } : {}
+  };
+  const llm = useLlm(config.provider, llmOptions);
+  const prompt = createChatPrompt(config.system || "", {
+    allowUnsafeUserTemplate: true
+  });
+  prompt.addUserMessage(config.message);
+  const parser = createParser(
+    config.parser,
+    config.parserOptions
+  );
+  const llmConfiguration = { llm, prompt, parser };
+  const hasFunctions = Array.isArray(
+    config.executorOptions?.functions
+  );
+  return hasFunctions ? createLlmFunctionExecutor(llmConfiguration, createOptions) : createLlmExecutor(llmConfiguration, createOptions);
+}
+function runConfig(config, overrides, createOptions) {
+  const executor = executorFromConfig(config, createOptions);
+  const data = mergeData(config.data, overrides?.data) ?? {};
+  const executorOptions = {
+    ...config.executorOptions,
+    ...overrides?.executorOptions
+  };
+  return executor.execute(data, executorOptions);
+}
+
+// src/config/parse.ts
+var import_js_yaml = require("js-yaml");
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function snippetOf(source) {
+  return source.length > 120 ? `${source.slice(0, 120)}\u2026` : source;
+}
+function formatFromExtension(pathOrUrl) {
+  const clean = pathOrUrl.split(/[?#]/)[0];
+  const dot = clean.lastIndexOf(".");
+  if (dot === -1) return void 0;
+  switch (clean.slice(dot).toLowerCase()) {
+    case ".json":
+      return "json";
+    case ".yml":
+    case ".yaml":
+      return "yaml";
+    case ".md":
+    case ".markdown":
+      return "markdown";
+    default:
+      return void 0;
+  }
+}
+function parseJsonSource(source, patch) {
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (cause) {
+    throw configParseFailedError(
+      { format: "json", snippet: snippetOf(source) },
+      { cause }
+    );
+  }
+  return normalizeConfig(parsed, patch);
+}
+function parseYamlSource(source, patch) {
+  let parsed;
+  try {
+    parsed = (0, import_js_yaml.load)(source);
+  } catch (cause) {
+    throw configParseFailedError(
+      { format: "yaml", snippet: snippetOf(source) },
+      { cause }
+    );
+  }
+  return normalizeConfig(parsed, patch);
+}
+function parseMarkdownSource(source, patch) {
+  const match = FRONTMATTER_RE.exec(source);
+  let frontmatter = {};
+  let body = source;
+  if (match) {
+    const [, fmBlock, bodyBlock] = match;
+    let parsed;
+    try {
+      parsed = (0, import_js_yaml.load)(fmBlock);
+    } catch (cause) {
+      throw configParseFailedError(
+        { format: "markdown", snippet: snippetOf(fmBlock) },
+        { cause }
+      );
+    }
+    frontmatter = isRecord(parsed) ? parsed : {};
+    body = bodyBlock;
+  }
+  const trimmedBody = body.trim();
+  const fmMessage = typeof frontmatter.message === "string" ? frontmatter.message.trim() : "";
+  if (fmMessage !== "" && trimmedBody !== "") {
+    throw configInvalidError({
+      field: "message",
+      expected: "either frontmatter `message` or a markdown body, not both"
+    });
+  }
+  const object = { ...frontmatter };
+  if (trimmedBody !== "") {
+    object.message = trimmedBody;
+  }
+  return normalizeConfig(object, patch);
+}
+function parseAutoSource(source, patch) {
+  let jsonParsed;
+  let jsonOk = false;
+  try {
+    jsonParsed = JSON.parse(source);
+    jsonOk = true;
+  } catch {
+  }
+  if (jsonOk) {
+    return normalizeConfig(jsonParsed, patch);
+  }
+  if (FRONTMATTER_RE.test(source)) {
+    return parseMarkdownSource(source, patch);
+  }
+  let yamlParsed;
+  let yamlOk = false;
+  try {
+    yamlParsed = (0, import_js_yaml.load)(source);
+    yamlOk = isRecord(yamlParsed);
+  } catch {
+  }
+  if (yamlOk) {
+    return normalizeConfig(yamlParsed, patch);
+  }
+  throw configParseFailedError({ format: "auto", snippet: snippetOf(source) });
+}
+async function parseExecutorConfig(source, opts) {
+  const { format, ...patch } = opts;
+  switch (format) {
+    case "json":
+      return parseJsonSource(source, patch);
+    case "yaml":
+      return parseYamlSource(source, patch);
+    case "markdown":
+      return parseMarkdownSource(source, patch);
+    case "auto":
+      return parseAutoSource(source, patch);
+    default:
+      return parseAutoSource(source, patch);
+  }
+}
+
+// src/config/fromUrl.ts
+async function loadConfigFromUrl(url, opts = {}) {
+  const { fetch: fetchImpl, init, format, ...patch } = opts;
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw createLlmExeError(
+      {
+        code: "request.http_error",
+        message: () => `No fetch implementation available to load config from "${url}".`,
+        resolution: "Pass a `fetch` implementation in options, or run on a platform with a global fetch."
+      },
+      { url }
+    );
+  }
+  const response = await doFetch(url, init);
+  if (!response.ok) {
+    throw createLlmExeError(
+      {
+        code: "request.http_error",
+        message: (ctx) => `Failed to fetch config from "${ctx.url}": ${ctx.status ?? ""} ${ctx.statusText ?? ""}`.trim(),
+        resolution: "Check the URL is reachable and returns the config body."
+      },
+      { url, status: response.status, statusText: response.statusText }
+    );
+  }
+  const text = await response.text();
+  const resolvedFormat = format ?? formatFromExtension(url) ?? "auto";
+  return parseExecutorConfig(text, { format: resolvedFormat, ...patch });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseExecutor,
@@ -7700,10 +8118,17 @@ function createStateItem(name, defaultValue) {
   createState,
   createStateItem,
   defineSchema,
+  executorFromConfig,
+  formatLlmExeErrorForLog,
   guards,
   isLlmExeError,
+  loadConfigFromUrl,
+  loadExecutorConfig,
+  parseExecutorConfig,
   registerHelpers,
   registerPartials,
+  runConfig,
+  serializeLlmExeError,
   useExecutors,
   useLlm,
   useLlmConfiguration,