llm-fns 1.0.18 → 1.0.20

package/dist/createCachedFetcher.d.ts

@@ -14,12 +14,7 @@ export interface CreateFetcherDependencies {
     prefix?: string;
     /** Time-to-live for cache entries, in milliseconds. */
     ttl?: number;
-    /** Request timeout in milliseconds. If not provided, no timeout is applied.**Restoring Corrected File**
-
-I'm now generating the corrected version of `src/createCachedFetcher.ts`. The primary fix is removing the extraneous text from the `set` method signature within the `CacheLike` interface. I've ensured the syntax is correct, and I'm confident the test run should now pass. After this is output, I plan to assess its integration within the wider project.
-
-
- */
+    /** Request timeout in milliseconds. If not provided, no timeout is applied. */
     timeout?: number;
     /** User-Agent string for requests. */
     userAgent?: string;

package/dist/createCachedFetcher.js

@@ -1,5 +1,4 @@
 "use strict";
-// src/createCachedFetcher.ts
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -7,20 +6,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CachedResponse = void 0;
 exports.createCachedFetcher = createCachedFetcher;
 const crypto_1 = __importDefault(require("crypto"));
-// A custom Response class to correctly handle the `.url` property on cache HITs.
-// This is an implementation detail and doesn't need to be exported.
 class CachedResponse extends Response {
     #finalUrl;
     constructor(body, init, finalUrl) {
         super(body, init);
         this.#finalUrl = finalUrl;
     }
-    // Override the read-only `url` property
     get url() {
         return this.#finalUrl;
     }
 }
 exports.CachedResponse = CachedResponse;
+/**
+ * Creates a deterministic hash of headers for cache key generation.
+ * Headers are sorted alphabetically to ensure consistency.
+ */
+function hashHeaders(headers) {
+    if (!headers)
+        return '';
+    let headerEntries;
+    if (headers instanceof Headers) {
+        headerEntries = Array.from(headers.entries());
+    }
+    else if (Array.isArray(headers)) {
+        headerEntries = headers;
+    }
+    else {
+        headerEntries = Object.entries(headers);
+    }
+    if (headerEntries.length === 0)
+        return '';
+    // Sort alphabetically by key for deterministic ordering
+    headerEntries.sort((a, b) => a[0].localeCompare(b[0]));
+    const headerString = headerEntries
+        .map(([key, value]) => `${key}:${value}`)
+        .join('|');
+    return crypto_1.default.createHash('md5').update(headerString).digest('hex');
+}
 /**
  * Factory function that creates a `fetch` replacement with a caching layer.
  * @param deps - Dependencies including the cache instance, prefix, TTL, and timeout.
@@ -30,8 +52,6 @@ function createCachedFetcher(deps) {
     const { cache, prefix = 'http-cache', ttl, timeout, userAgent, fetch: customFetch, shouldCache } = deps;
     const fetchImpl = customFetch ?? fetch;
     const fetchWithTimeout = async (url, options) => {
-        // Correctly merge headers using Headers API to handle various input formats (plain object, Headers instance, array)
-        // and avoid issues with spreading Headers objects which can lead to lost headers or Symbol errors.
         const headers = new Headers(options?.headers);
         if (userAgent) {
             headers.set('User-Agent', userAgent);
@@ -70,10 +90,7 @@ function createCachedFetcher(deps) {
             clearTimeout(timeoutId);
         }
     };
-    // This is the actual fetcher implementation, returned by the factory.
-    // It "closes over" the dependencies provided to the factory.
     return async (url, options) => {
-        // Determine the request method. Default to GET for fetch.
         let method = 'GET';
         if (options?.method) {
             method = options.method;
@@ -87,7 +104,7 @@ function createCachedFetcher(deps) {
             return fetchWithTimeout(url, options);
         }
         let cacheKey = `${prefix}:${urlString}`;
-        // If POST (or others with body), append hash of body to cache key
+        // Hash body for POST requests
         if (method.toUpperCase() === 'POST' && options?.body) {
             let bodyStr = '';
             if (typeof options.body === 'string') {
@@ -97,7 +114,6 @@ function createCachedFetcher(deps) {
                 bodyStr = options.body.toString();
             }
             else {
-                // Fallback for other types, though mostly we expect string/JSON here
                 try {
                     bodyStr = JSON.stringify(options.body);
                 }
@@ -105,13 +121,17 @@ function createCachedFetcher(deps) {
                     bodyStr = 'unserializable';
                 }
             }
-            const hash = crypto_1.default.createHash('md5').update(bodyStr).digest('hex');
-            cacheKey += `:${hash}`;
+            const bodyHash = crypto_1.default.createHash('md5').update(bodyStr).digest('hex');
+            cacheKey += `:body:${bodyHash}`;
+        }
+        // Hash all request headers into cache key
+        const headersHash = hashHeaders(options?.headers);
+        if (headersHash) {
+            cacheKey += `:headers:${headersHash}`;
         }
         // 1. Check the cache
         const cachedItem = await cache.get(cacheKey);
         if (cachedItem) {
-            // Decode the base64 body back into a Buffer.
             const body = Buffer.from(cachedItem.bodyBase64, 'base64');
             return new CachedResponse(body, {
                 status: cachedItem.status,
@@ -135,7 +155,6 @@ function createCachedFetcher(deps) {
                     }
                 }
                 else {
-                    // Default behavior: check for .error in JSON responses
                     const contentType = response.headers.get('content-type');
                     if (contentType && contentType.includes('application/json')) {
                         const checkClone = response.clone();
@@ -154,7 +173,6 @@ function createCachedFetcher(deps) {
                 if (isCacheable) {
                     const responseClone = response.clone();
                     const bodyBuffer = await responseClone.arrayBuffer();
-                    // Convert ArrayBuffer to a base64 string for safe JSON serialization.
                     const bodyBase64 = Buffer.from(bodyBuffer).toString('base64');
                     const headers = Object.fromEntries(response.headers.entries());
                     const itemToCache = {

package/dist/createJsonSchemaLlmClient.d.ts

@@ -1,6 +1,13 @@
 import OpenAI from 'openai';
-import { PromptFunction, LlmPromptOptions } from "./createLlmClient.js";
-export type JsonSchemaLlmClientOptions = Omit<LlmPromptOptions, 'messages' | 'response_format'> & {
+import { PromptFunction, LlmCommonOptions } from "./createLlmClient.js";
+export declare class SchemaValidationError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Options for JSON schema prompt functions.
+ * Extends common options with JSON-specific settings.
+ */
+export interface JsonSchemaLlmClientOptions extends LlmCommonOptions {
     maxRetries?: number;
     /**
      * If true, passes `response_format: { type: 'json_object' }` to the model.
@@ -22,7 +29,7 @@ export type JsonSchemaLlmClientOptions = Omit<LlmPromptOptions, 'messages' | 're
      * If not provided, an AJV-based validator will be used.
      */
     validator?: (data: any) => any;
-};
+}
 export interface CreateJsonSchemaLlmClientParams {
     prompt: PromptFunction;
     fallbackPrompt?: PromptFunction;

package/dist/createJsonSchemaLlmClient.js

@@ -3,13 +3,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaValidationError = void 0;
 exports.createJsonSchemaLlmClient = createJsonSchemaLlmClient;
 const ajv_1 = __importDefault(require("ajv"));
 const createLlmRetryClient_js_1 = require("./createLlmRetryClient.js");
+class SchemaValidationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SchemaValidationError';
+    }
+}
+exports.SchemaValidationError = SchemaValidationError;
 function createJsonSchemaLlmClient(params) {
     const { prompt, fallbackPrompt, disableJsonFixer = false } = params;
     const llmRetryClient = (0, createLlmRetryClient_js_1.createLlmRetryClient)({ prompt, fallbackPrompt });
-    const ajv = new ajv_1.default({ strict: false }); // Initialize AJV
+    const ajv = new ajv_1.default({ strict: false });
     async function _tryToFixJson(brokenResponse, schemaJsonString, errorDetails, options) {
         const fixupPrompt = `
 An attempt to generate a JSON object resulted in the following output, which is either not valid JSON or does not conform to the required schema.
@@ -37,7 +45,7 @@ ${brokenResponse}
         const response_format = useResponseFormat
             ? { type: 'json_object' }
             : undefined;
-        const { maxRetries, useResponseFormat: _useResponseFormat, ...restOptions } = options || {};
+        const { maxRetries, useResponseFormat: _useResponseFormat, beforeValidation, validator, ...restOptions } = options || {};
         const completion = await prompt({
             messages,
             response_format,
@@ -51,7 +59,6 @@ ${brokenResponse}
     }
     async function _parseOrFixJson(llmResponseString, schemaJsonString, options) {
         let jsonDataToParse = llmResponseString.trim();
-        // Robust handling for responses wrapped in markdown code blocks
         const codeBlockRegex = /```(?:json)?\s*([\s\S]*?)\s*```/;
         const match = codeBlockRegex.exec(jsonDataToParse);
         if (match && match[1]) {
@@ -64,10 +71,14 @@ ${brokenResponse}
             return JSON.parse(jsonDataToParse);
         }
         catch (parseError) {
+            // Only attempt to fix SyntaxErrors (JSON parsing errors).
+            // Other errors (like runtime errors) should bubble up.
+            if (!(parseError instanceof SyntaxError)) {
+                throw parseError;
+            }
             if (disableJsonFixer) {
-                throw parseError; // re-throw original error
+                throw parseError;
             }
-            // Attempt a one-time fix before failing.
             const errorDetails = `JSON Parse Error: ${parseError.message}`;
             const fixedResponse = await _tryToFixJson(jsonDataToParse, schemaJsonString, errorDetails, options);
             if (fixedResponse) {
@@ -75,11 +86,10 @@ ${brokenResponse}
                     return JSON.parse(fixedResponse);
                 }
                 catch (e) {
-                    // Fix-up failed, throw original error.
                     throw parseError;
                 }
             }
-            throw parseError; // if no fixed response
+            throw parseError;
         }
     }
     async function _validateOrFix(jsonData, validator, schemaJsonString, options) {
@@ -90,10 +100,14 @@ ${brokenResponse}
             return validator(jsonData);
         }
         catch (validationError) {
+            // Only attempt to fix known validation errors (SchemaValidationError).
+            // Arbitrary errors thrown by custom validators (e.g. "Database Error") should bubble up.
+            if (!(validationError instanceof SchemaValidationError)) {
+                throw validationError;
+            }
             if (disableJsonFixer) {
                 throw validationError;
             }
-            // Attempt a one-time fix for schema validation errors.
             const errorDetails = `Schema Validation Error: ${validationError.message}`;
             const fixedResponse = await _tryToFixJson(JSON.stringify(jsonData, null, 2), schemaJsonString, errorDetails, options);
             if (fixedResponse) {
@@ -105,11 +119,10 @@ ${brokenResponse}
                     return validator(fixedJsonData);
                 }
                 catch (e) {
-                    // Fix-up failed, throw original validation error
                     throw validationError;
                 }
             }
-            throw validationError; // if no fixed response
+            throw validationError;
         }
     }
     function _getJsonPromptConfig(messages, schema, options) {
@@ -120,12 +133,9 @@ Do NOT include any other text, explanations, or markdown formatting (like \`\`\`
 
 JSON schema:
 ${schemaJsonString}`;
-        // Clone messages to avoid mutating the input
         const finalMessages = [...messages];
-        // Find the first system message to append instructions to
         const systemMessageIndex = finalMessages.findIndex(m => m.role === 'system');
         if (systemMessageIndex !== -1) {
-            // Append to existing system message
             const existingContent = finalMessages[systemMessageIndex].content;
             finalMessages[systemMessageIndex] = {
                 ...finalMessages[systemMessageIndex],
@@ -133,7 +143,6 @@ ${schemaJsonString}`;
             };
         }
         else {
-            // Prepend new system message
             finalMessages.unshift({
                 role: 'system',
                 content: commonPromptFooter
@@ -146,14 +155,13 @@ ${schemaJsonString}`;
         return { finalMessages, schemaJsonString, response_format };
     }
     async function promptJson(messages, schema, options) {
-        // Default validator using AJV
         const defaultValidator = (data) => {
             try {
                 const validate = ajv.compile(schema);
                 const valid = validate(data);
                 if (!valid) {
-                    const errors = validate.errors?.map(e => `${e.instancePath} ${e.message}`).join(', ');
-                    throw new Error(`AJV Validation Error: ${errors}`);
+                    const errors = (validate.errors || []).map(e => `${e.instancePath} ${e.message}`).join(', ');
+                    throw new SchemaValidationError(`AJV Validation Error: ${errors}`);
                 }
                 return data;
             }
@@ -169,29 +177,40 @@ ${schemaJsonString}`;
                 jsonData = await _parseOrFixJson(llmResponseString, schemaJsonString, options);
             }
             catch (parseError) {
-                const errorMessage = `Your previous response resulted in an error.
+                // Only wrap SyntaxErrors (JSON parse errors) for retry.
+                if (parseError instanceof SyntaxError) {
+                    const errorMessage = `Your previous response resulted in an error.
 Error Type: JSON_PARSE_ERROR
 Error Details: ${parseError.message}
 The response provided was not valid JSON. Please correct it.`;
-                throw new createLlmRetryClient_js_1.LlmRetryError(errorMessage, 'JSON_PARSE_ERROR', undefined, llmResponseString);
+                    throw new createLlmRetryClient_js_1.LlmRetryError(errorMessage, 'JSON_PARSE_ERROR', undefined, llmResponseString);
+                }
+                // Rethrow other errors (e.g. fatal errors, runtime errors)
+                throw parseError;
             }
             try {
                 const validatedData = await _validateOrFix(jsonData, validator, schemaJsonString, options);
                 return validatedData;
             }
             catch (validationError) {
-                // We assume the validator throws an error with a meaningful message
-                const rawResponseForError = JSON.stringify(jsonData, null, 2);
-                const errorDetails = validationError.message;
-                const errorMessage = `Your previous response resulted in an error.
+                // Only wrap known validation errors for retry.
+                if (validationError instanceof SchemaValidationError) {
+                    const rawResponseForError = JSON.stringify(jsonData, null, 2);
+                    const errorDetails = validationError.message;
+                    const errorMessage = `Your previous response resulted in an error.
 Error Type: SCHEMA_VALIDATION_ERROR
 Error Details: ${errorDetails}
 The response was valid JSON but did not conform to the required schema. Please review the errors and the schema to provide a corrected response.`;
-                throw new createLlmRetryClient_js_1.LlmRetryError(errorMessage, 'CUSTOM_ERROR', validationError, rawResponseForError);
+                    throw new createLlmRetryClient_js_1.LlmRetryError(errorMessage, 'CUSTOM_ERROR', validationError, rawResponseForError);
+                }
+                // Rethrow other errors
+                throw validationError;
             }
         };
+        const { maxRetries, useResponseFormat: _useResponseFormat, beforeValidation, validator: _validator, ...restOptions } = options || {};
         const retryOptions = {
-            ...options,
+            ...restOptions,
+            maxRetries,
             messages: finalMessages,
             response_format,
             validate: processResponse

package/dist/createLlmClient.d.ts

@@ -1,5 +1,9 @@
 import OpenAI from "openai";
 import type PQueue from 'p-queue';
+export declare class LlmFatalError extends Error {
+    readonly cause?: any | undefined;
+    constructor(message: string, cause?: any | undefined);
+}
 export declare function countChars(message: OpenAI.Chat.Completions.ChatCompletionMessageParam): number;
 export declare function truncateSingleMessage(message: OpenAI.Chat.Completions.ChatCompletionMessageParam, charLimit: number): OpenAI.Chat.Completions.ChatCompletionMessageParam;
 export declare function truncateMessages(messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], limit: number): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
@@ -21,12 +25,24 @@ export type OpenRouterResponseFormat = {
     };
 };
 /**
- * Options for the individual "prompt" function calls.
- * These can override defaults or add call-specific parameters.
- * 'messages' is a required property, inherited from OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming.
+ * Request-level options passed to the OpenAI SDK.
+ * These are separate from the body parameters.
  */
-export interface LlmPromptOptions extends Omit<OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming, 'model' | 'response_format' | 'modalities' | 'messages'> {
-    messages: string | OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+export interface LlmRequestOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeout?: number;
+}
+/**
+ * Merges two LlmRequestOptions objects.
+ * Headers are merged (override wins on conflict), other properties are replaced.
+ */
+export declare function mergeRequestOptions(base?: LlmRequestOptions, override?: LlmRequestOptions): LlmRequestOptions | undefined;
+/**
+ * Common options shared by all prompt functions.
+ * Does NOT include messages - those are handled separately.
+ */
+export interface LlmCommonOptions {
     model?: ModelConfig;
     retries?: number;
     /** @deprecated Use `reasoning` object instead. */
@@ -35,6 +51,31 @@ export interface LlmPromptOptions extends Omit<OpenAI.Chat.Completions.ChatCompl
     image_config?: {
         aspect_ratio?: string;
     };
+    requestOptions?: LlmRequestOptions;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    stop?: string | string[];
+    reasoning_effort?: 'low' | 'medium' | 'high';
+    seed?: number;
+    user?: string;
+    tools?: OpenAI.Chat.Completions.ChatCompletionTool[];
+    tool_choice?: OpenAI.Chat.Completions.ChatCompletionToolChoiceOption;
+}
+/**
+ * Options for the individual "prompt" function calls.
+ * Allows messages as string or array for convenience.
+ */
+export interface LlmPromptOptions extends LlmCommonOptions {
+    messages: string | OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+}
+/**
+ * Internal normalized params - messages is always an array.
+ */
+export interface LlmPromptParams extends LlmCommonOptions {
+    messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[];
 }
 /**
  * Options required to create an instance of the LlmClient.
@@ -45,8 +86,13 @@ export interface CreateLlmClientParams {
     defaultModel: ModelConfig;
     maxConversationChars?: number;
     queue?: PQueue;
+    defaultRequestOptions?: LlmRequestOptions;
 }
-export declare function normalizeOptions(arg1: string | LlmPromptOptions, arg2?: Omit<LlmPromptOptions, 'messages'>): LlmPromptOptions;
+/**
+ * Normalizes input arguments to LlmPromptParams.
+ * Handles string shorthand and messages-as-string.
+ */
+export declare function normalizeOptions(arg1: string | LlmPromptOptions, arg2?: LlmCommonOptions): LlmPromptParams;
 /**
  * Factory function that creates a GPT "prompt" function.
  * @param params - The core dependencies (API key, base URL, default model).
@@ -54,15 +100,15 @@ export declare function normalizeOptions(arg1: string | LlmPromptOptions, arg2?:
  */
 export declare function createLlmClient(params: CreateLlmClientParams): {
     prompt: {
-        (content: string, options?: Omit<LlmPromptOptions, "messages">): Promise<OpenAI.Chat.Completions.ChatCompletion>;
+        (content: string, options?: LlmCommonOptions): Promise<OpenAI.Chat.Completions.ChatCompletion>;
         (options: LlmPromptOptions): Promise<OpenAI.Chat.Completions.ChatCompletion>;
     };
     promptText: {
-        (content: string, options?: Omit<LlmPromptOptions, "messages">): Promise<string>;
+        (content: string, options?: LlmCommonOptions): Promise<string>;
         (options: LlmPromptOptions): Promise<string>;
     };
     promptImage: {
-        (content: string, options?: Omit<LlmPromptOptions, "messages">): Promise<Buffer>;
+        (content: string, options?: LlmCommonOptions): Promise<Buffer>;
         (options: LlmPromptOptions): Promise<Buffer>;
     };
 };

package/dist/createLlmClient.js

@@ -1,11 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LlmFatalError = void 0;
 exports.countChars = countChars;
 exports.truncateSingleMessage = truncateSingleMessage;
 exports.truncateMessages = truncateMessages;
+exports.mergeRequestOptions = mergeRequestOptions;
 exports.normalizeOptions = normalizeOptions;
 exports.createLlmClient = createLlmClient;
 const retryUtils_js_1 = require("./retryUtils.js");
+class LlmFatalError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'LlmFatalError';
+        this.cause = cause;
+    }
+}
+exports.LlmFatalError = LlmFatalError;
 function countChars(message) {
     if (!message.content)
         return 0;
@@ -49,14 +61,12 @@ function truncateSingleMessage(message, charLimit) {
         return messageCopy;
     }
     if (Array.isArray(messageCopy.content)) {
-        // Complex case: multipart message.
-        // Strategy: consolidate text, remove images if needed, then truncate text.
         const textParts = messageCopy.content.filter((p) => p.type === 'text');
         const imageParts = messageCopy.content.filter((p) => p.type === 'image_url');
         let combinedText = textParts.map((p) => p.text).join('\n');
         let keptImages = [...imageParts];
         while (combinedText.length + (keptImages.length * 2500) > charLimit && keptImages.length > 0) {
-            keptImages.pop(); // remove images from the end
+            keptImages.pop();
         }
         const imageChars = keptImages.length * 2500;
         const textCharLimit = charLimit - imageChars;
@@ -89,7 +99,6 @@ function truncateMessages(messages, limit) {
     }
     const mutableOtherMessages = JSON.parse(JSON.stringify(otherMessages));
     let excessChars = totalChars - limit;
-    // Truncate messages starting from the second one.
     for (let i = 1; i < mutableOtherMessages.length; i++) {
         if (excessChars <= 0)
             break;
@@ -100,7 +109,6 @@ function truncateMessages(messages, limit) {
         mutableOtherMessages[i] = truncateSingleMessage(message, newCharCount);
         excessChars -= charsToCut;
     }
-    // If still over limit, truncate the first message.
     if (excessChars > 0) {
         const firstMessage = mutableOtherMessages[0];
         const firstMessageChars = countChars(firstMessage);
@@ -108,7 +116,6 @@ function truncateMessages(messages, limit) {
         const newCharCount = firstMessageChars - charsToCut;
         mutableOtherMessages[0] = truncateSingleMessage(firstMessage, newCharCount);
     }
-    // Filter out empty messages (char count is 0)
     const finalMessages = mutableOtherMessages.filter(msg => countChars(msg) > 0);
     return systemMessage ? [systemMessage, ...finalMessages] : finalMessages;
 }
@@ -135,7 +142,6 @@ function concatMessageText(messages) {
 }
 function getPromptSummary(messages) {
     const fullText = concatMessageText(messages);
-    // Replace multiple whitespace chars with a single space and trim.
     const cleanedText = fullText.replace(/\s+/g, ' ').trim();
     if (cleanedText.length <= 50) {
         return cleanedText;
@@ -149,6 +155,30 @@ function getPromptSummary(messages) {
     const middle = cleanedText.substring(midStart, midEnd);
     return `${start}...${middle}...${end}`;
 }
+/**
+ * Merges two LlmRequestOptions objects.
+ * Headers are merged (override wins on conflict), other properties are replaced.
+ */
+function mergeRequestOptions(base, override) {
+    if (!base && !override)
+        return undefined;
+    if (!base)
+        return override;
+    if (!override)
+        return base;
+    return {
+        ...base,
+        ...override,
+        headers: {
+            ...base.headers,
+            ...override.headers
+        }
+    };
+}
+/**
+ * Normalizes input arguments to LlmPromptParams.
+ * Handles string shorthand and messages-as-string.
+ */
 function normalizeOptions(arg1, arg2) {
     if (typeof arg1 === 'string') {
         return {
@@ -171,14 +201,12 @@ function normalizeOptions(arg1, arg2) {
  * @returns An async function `prompt` ready to make OpenAI calls.
  */
 function createLlmClient(params) {
-    const { openai, defaultModel: factoryDefaultModel, maxConversationChars, queue } = params;
-    const getCompletionParams = (options) => {
-        const { model: callSpecificModel, messages, reasoning_effort, retries, ...restApiOptions } = options;
-        // Ensure messages is an array (it should be if normalized, but for safety/types)
-        const messagesArray = typeof messages === 'string'
-            ? [{ role: 'user', content: messages }]
+    const { openai, defaultModel: factoryDefaultModel, maxConversationChars, queue, defaultRequestOptions } = params;
+    const getCompletionParams = (promptParams) => {
+        const { model: callSpecificModel, messages, retries, requestOptions, ...restApiOptions } = promptParams;
+        const finalMessages = maxConversationChars
+            ? truncateMessages(messages, maxConversationChars)
             : messages;
-        const finalMessages = maxConversationChars ? truncateMessages(messagesArray, maxConversationChars) : messagesArray;
         const baseConfig = typeof factoryDefaultModel === 'object' && factoryDefaultModel !== null
             ? factoryDefaultModel
             : (typeof factoryDefaultModel === 'string' ? { model: factoryDefaultModel } : {});
@@ -196,15 +224,24 @@ function createLlmClient(params) {
             messages: finalMessages,
             ...restApiOptions,
         };
-        return { completionParams, modelToUse, finalMessages, retries };
+        const mergedRequestOptions = mergeRequestOptions(defaultRequestOptions, requestOptions);
+        return { completionParams, modelToUse, finalMessages, retries, requestOptions: mergedRequestOptions };
     };
     async function prompt(arg1, arg2) {
-        const options = normalizeOptions(arg1, arg2);
-        const { completionParams, finalMessages, retries } = getCompletionParams(options);
+        const promptParams = normalizeOptions(arg1, arg2);
+        const { completionParams, finalMessages, retries, requestOptions } = getCompletionParams(promptParams);
         const promptSummary = getPromptSummary(finalMessages);
         const apiCall = async () => {
             const task = () => (0, retryUtils_js_1.executeWithRetry)(async () => {
-                return openai.chat.completions.create(completionParams);
+                try {
+                    return await openai.chat.completions.create(completionParams, requestOptions);
+                }
+                catch (error) {
+                    if (error?.status === 400 || error?.status === 401 || error?.status === 403) {
+                        throw new LlmFatalError(error.message || 'Fatal API Error', error);
+                    }
+                    throw error;
+                }
             }, async (completion) => {
                 if (completion.error) {
                     return {
@@ -213,8 +250,9 @@ function createLlmClient(params) {
                 }
                 return { isValid: true, data: completion };
             }, retries ?? 3, undefined, (error) => {
-                // Do not retry if the API key is invalid (401) or if the error code explicitly states it.
-                if (error?.status === 401 || error?.code === 'invalid_api_key') {
+                if (error instanceof LlmFatalError)
+                    return false;
+                if (error?.status === 400 || error?.status === 401 || error?.status === 403 || error?.code === 'invalid_api_key') {
                     return false;
                 }
                 return true;
@@ -225,8 +263,8 @@ function createLlmClient(params) {
         return apiCall();
     }
     async function promptText(arg1, arg2) {
-        const options = normalizeOptions(arg1, arg2);
-        const response = await prompt(options);
+        const promptParams = normalizeOptions(arg1, arg2);
+        const response = await prompt(promptParams);
         const content = response.choices[0]?.message?.content;
         if (content === null || content === undefined) {
             throw new Error("LLM returned no text content.");
@@ -234,8 +272,8 @@ function createLlmClient(params) {
         return content;
     }
     async function promptImage(arg1, arg2) {
-        const options = normalizeOptions(arg1, arg2);
-        const response = await prompt(options);
+        const promptParams = normalizeOptions(arg1, arg2);
+        const response = await prompt(promptParams);
         const message = response.choices[0]?.message;
         if (message.images && Array.isArray(message.images) && message.images.length > 0) {
             const imageUrl = message.images[0].image_url.url;

package/dist/createLlmClient.spec.js

@@ -37,4 +37,76 @@ const createLlmClient_js_1 = require("./createLlmClient.js");
             temperature: 0.7
         });
     });
+    (0, vitest_1.it)('should include requestOptions when provided', () => {
+        const result = (0, createLlmClient_js_1.normalizeOptions)('Hello world', {
+            temperature: 0.5,
+            requestOptions: {
+                headers: { 'X-Custom': 'value' },
+                timeout: 5000
+            }
+        });
+        (0, vitest_1.expect)(result).toEqual({
+            messages: [{ role: 'user', content: 'Hello world' }],
+            temperature: 0.5,
+            requestOptions: {
+                headers: { 'X-Custom': 'value' },
+                timeout: 5000
+            }
+        });
+    });
+});
+(0, vitest_1.describe)('mergeRequestOptions', () => {
+    (0, vitest_1.it)('should return undefined when both are undefined', () => {
+        const result = (0, createLlmClient_js_1.mergeRequestOptions)(undefined, undefined);
+        (0, vitest_1.expect)(result).toBeUndefined();
+    });
+    (0, vitest_1.it)('should return override when base is undefined', () => {
+        const override = { timeout: 5000 };
+        const result = (0, createLlmClient_js_1.mergeRequestOptions)(undefined, override);
+        (0, vitest_1.expect)(result).toBe(override);
+    });
+    (0, vitest_1.it)('should return base when override is undefined', () => {
+        const base = { timeout: 5000 };
+        const result = (0, createLlmClient_js_1.mergeRequestOptions)(base, undefined);
+        (0, vitest_1.expect)(result).toBe(base);
+    });
+    (0, vitest_1.it)('should merge headers from both', () => {
+        const base = {
+            headers: { 'X-Base': 'base-value' },
+            timeout: 5000
+        };
+        const override = {
+            headers: { 'X-Override': 'override-value' }
+        };
+        const result = (0, createLlmClient_js_1.mergeRequestOptions)(base, override);
+        (0, vitest_1.expect)(result).toEqual({
+            headers: {
+                'X-Base': 'base-value',
+                'X-Override': 'override-value'
+            },
+            timeout: 5000
+        });
+    });
+    (0, vitest_1.it)('should override scalar properties', () => {
+        const base = { timeout: 5000 };
+        const override = { timeout: 10000 };
+        const result = (0, createLlmClient_js_1.mergeRequestOptions)(base, override);
+        (0, vitest_1.expect)(result).toEqual({ timeout: 10000, headers: {} });
+    });
+    (0, vitest_1.it)('should override conflicting headers', () => {
+        const base = {
+            headers: { 'X-Shared': 'base-value', 'X-Base': 'base' }
+        };
+        const override = {
+            headers: { 'X-Shared': 'override-value', 'X-Override': 'override' }
+        };
+        const result = (0, createLlmClient_js_1.mergeRequestOptions)(base, override);
+        (0, vitest_1.expect)(result).toEqual({
+            headers: {
+                'X-Shared': 'override-value',
+                'X-Base': 'base',
+                'X-Override': 'override'
+            }
+        });
+    });
 });

package/dist/createLlmRetryClient.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { PromptFunction, LlmPromptOptions } from "./createLlmClient.js";
+import { PromptFunction, LlmCommonOptions, LlmPromptOptions } from "./createLlmClient.js";
 export declare class LlmRetryError extends Error {
     readonly message: string;
     readonly type: 'JSON_PARSE_ERROR' | 'CUSTOM_ERROR';
@@ -16,33 +16,38 @@ export declare class LlmRetryAttemptError extends Error {
     readonly mode: 'main' | 'fallback';
     readonly conversation: OpenAI.Chat.Completions.ChatCompletionMessageParam[];
     readonly attemptNumber: number;
-    constructor(message: string, mode: 'main' | 'fallback', conversation: OpenAI.Chat.Completions.ChatCompletionMessageParam[], attemptNumber: number, options?: ErrorOptions);
+    readonly error: Error;
+    constructor(message: string, mode: 'main' | 'fallback', conversation: OpenAI.Chat.Completions.ChatCompletionMessageParam[], attemptNumber: number, error: Error, options?: ErrorOptions);
 }
 export interface LlmRetryResponseInfo {
     mode: 'main' | 'fallback';
     conversation: OpenAI.Chat.Completions.ChatCompletionMessageParam[];
     attemptNumber: number;
 }
-export type LlmRetryOptions<T = any> = LlmPromptOptions & {
+/**
+ * Options for retry prompt functions.
+ * Extends common options with retry-specific settings.
+ */
+export interface LlmRetryOptions<T = any> extends LlmCommonOptions {
     maxRetries?: number;
     validate?: (response: any, info: LlmRetryResponseInfo) => Promise<T>;
-};
+}
 export interface CreateLlmRetryClientParams {
     prompt: PromptFunction;
     fallbackPrompt?: PromptFunction;
 }
 export declare function createLlmRetryClient(params: CreateLlmRetryClientParams): {
     promptRetry: {
-        <T = OpenAI.Chat.Completions.ChatCompletion>(content: string, options?: Omit<LlmRetryOptions<T>, "messages">): Promise<T>;
-        <T = OpenAI.Chat.Completions.ChatCompletion>(options: LlmRetryOptions<T>): Promise<T>;
+        <T = OpenAI.Chat.Completions.ChatCompletion>(content: string, options?: LlmRetryOptions<T>): Promise<T>;
+        <T = OpenAI.Chat.Completions.ChatCompletion>(options: LlmPromptOptions & LlmRetryOptions<T>): Promise<T>;
     };
     promptTextRetry: {
-        <T = string>(content: string, options?: Omit<LlmRetryOptions<T>, "messages">): Promise<T>;
-        <T = string>(options: LlmRetryOptions<T>): Promise<T>;
+        <T = string>(content: string, options?: LlmRetryOptions<T>): Promise<T>;
+        <T = string>(options: LlmPromptOptions & LlmRetryOptions<T>): Promise<T>;
     };
     promptImageRetry: {
-        <T = Buffer<ArrayBufferLike>>(content: string, options?: Omit<LlmRetryOptions<T>, "messages">): Promise<T>;
-        <T = Buffer<ArrayBufferLike>>(options: LlmRetryOptions<T>): Promise<T>;
+        <T = Buffer<ArrayBufferLike>>(content: string, options?: LlmRetryOptions<T>): Promise<T>;
+        <T = Buffer<ArrayBufferLike>>(options: LlmPromptOptions & LlmRetryOptions<T>): Promise<T>;
     };
 };
 export type LlmRetryClient = ReturnType<typeof createLlmRetryClient>;

package/dist/createLlmRetryClient.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LlmRetryAttemptError = exports.LlmRetryExhaustedError = exports.LlmRetryError = void 0;
 exports.createLlmRetryClient = createLlmRetryClient;
 const createLlmClient_js_1 = require("./createLlmClient.js");
-// Custom error for the querier to handle, allowing retries with structured feedback.
 class LlmRetryError extends Error {
     message;
     type;
@@ -28,33 +27,39 @@ class LlmRetryExhaustedError extends Error {
     }
 }
 exports.LlmRetryExhaustedError = LlmRetryExhaustedError;
-// This error is thrown by LlmRetryClient for each failed attempt.
-// It wraps the underlying error (from API call or validation) and adds context.
 class LlmRetryAttemptError extends Error {
     message;
     mode;
     conversation;
     attemptNumber;
-    constructor(message, mode, conversation, attemptNumber, options) {
+    error;
+    constructor(message, mode, conversation, attemptNumber, error, options) {
         super(message, options);
         this.message = message;
         this.mode = mode;
         this.conversation = conversation;
         this.attemptNumber = attemptNumber;
+        this.error = error;
         this.name = 'LlmRetryAttemptError';
     }
 }
 exports.LlmRetryAttemptError = LlmRetryAttemptError;
+function normalizeRetryOptions(arg1, arg2) {
+    const baseParams = (0, createLlmClient_js_1.normalizeOptions)(arg1, arg2);
+    return {
+        ...baseParams,
+        ...arg2,
+        messages: baseParams.messages
+    };
+}
 function constructLlmMessages(initialMessages, attemptNumber, previousError) {
     if (attemptNumber === 0) {
-        // First attempt
         return initialMessages;
     }
     if (!previousError) {
-        // Should not happen for attempt > 0, but as a safeguard...
         throw new Error("Invariant violation: previousError is missing for a retry attempt.");
     }
-    const cause = previousError.cause;
+    const cause = previousError.error;
     if (!(cause instanceof LlmRetryError)) {
         throw Error('cause must be an instanceof LlmRetryError');
     }
@@ -64,10 +69,8 @@ function constructLlmMessages(initialMessages, attemptNumber, previousError) {
 }
 function createLlmRetryClient(params) {
     const { prompt, fallbackPrompt } = params;
-    async function runPromptLoop(options, responseType) {
-        const { maxRetries = 3, validate, messages, ...restOptions } = options;
-        // Ensure messages is an array (normalizeOptions ensures this but types might be loose)
-        const initialMessages = messages;
+    async function runPromptLoop(retryParams, responseType) {
+        const { maxRetries = 3, validate, messages: initialMessages, ...restOptions } = retryParams;
         let lastError;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             const useFallback = !!fallbackPrompt && attempt > 0;
@@ -111,7 +114,6 @@ function createLlmRetryClient(params) {
                         throw new LlmRetryError("LLM returned no image.", 'CUSTOM_ERROR', undefined, JSON.stringify(completion));
                     }
                 }
-                // Construct conversation history for success or potential error reporting
                 const finalConversation = [...currentMessages];
                 if (assistantMessage) {
                     finalConversation.push(assistantMessage);
@@ -128,21 +130,18 @@ function createLlmRetryClient(params) {
                 return dataToProcess;
             }
             catch (error) {
+                if (error instanceof createLlmClient_js_1.LlmFatalError) {
+                    const fatalAttemptError = new LlmRetryAttemptError(`Fatal error on attempt ${attempt + 1}: ${error.message}`, mode, currentMessages, attempt, error, { cause: lastError });
+                    throw new LlmRetryExhaustedError(`Operation failed with fatal error on attempt ${attempt + 1}.`, { cause: fatalAttemptError });
+                }
                 if (error instanceof LlmRetryError) {
-                    // This is a recoverable error, so we'll create a detailed attempt error and continue the loop.
                     const conversationForError = [...currentMessages];
-                    // If the error contains the raw response (e.g. the invalid text), add it to history
-                    // so the LLM knows what it generated previously.
                     if (error.rawResponse) {
                         conversationForError.push({ role: 'assistant', content: error.rawResponse });
                     }
-                    else if (responseType === 'raw' && error.details) {
-                        // For raw mode, if we have details, maybe we can infer something, but usually rawResponse is key.
-                    }
-                    lastError = new LlmRetryAttemptError(`Attempt ${attempt + 1} failed.`, mode, conversationForError, attempt, { cause: error });
+                    lastError = new LlmRetryAttemptError(`Attempt ${attempt + 1} failed: ${error.message}`, mode, conversationForError, attempt, error, { cause: lastError });
                 }
                 else {
-                    // This is a non-recoverable error (e.g., network, API key), so we re-throw it immediately.
                     throw error;
                 }
             }
@@ -150,16 +149,16 @@ function createLlmRetryClient(params) {
         throw new LlmRetryExhaustedError(`Operation failed after ${maxRetries + 1} attempts.`, { cause: lastError });
     }
     async function promptRetry(arg1, arg2) {
-        const options = (0, createLlmClient_js_1.normalizeOptions)(arg1, arg2);
-        return runPromptLoop(options, 'raw');
+        const retryParams = normalizeRetryOptions(arg1, arg2);
+        return runPromptLoop(retryParams, 'raw');
     }
     async function promptTextRetry(arg1, arg2) {
-        const options = (0, createLlmClient_js_1.normalizeOptions)(arg1, arg2);
-        return runPromptLoop(options, 'text');
+        const retryParams = normalizeRetryOptions(arg1, arg2);
+        return runPromptLoop(retryParams, 'text');
     }
     async function promptImageRetry(arg1, arg2) {
-        const options = (0, createLlmClient_js_1.normalizeOptions)(arg1, arg2);
-        return runPromptLoop(options, 'image');
+        const retryParams = normalizeRetryOptions(arg1, arg2);
+        return runPromptLoop(retryParams, 'image');
     }
     return { promptRetry, promptTextRetry, promptImageRetry };
 }

package/dist/createZodLlmClient.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeZodArgs = normalizeZodArgs;
 exports.createZodLlmClient = createZodLlmClient;
 const z = __importStar(require("zod"));
+const createJsonSchemaLlmClient_js_1 = require("./createJsonSchemaLlmClient.js");
 function isZodSchema(obj) {
     return (typeof obj === 'object' &&
         obj !== null &&
@@ -94,7 +95,15 @@ function createZodLlmClient(params) {
             unrepresentable: 'any'
         });
         const zodValidator = (data) => {
-            return dataExtractionSchema.parse(data);
+            try {
+                return dataExtractionSchema.parse(data);
+            }
+            catch (error) {
+                if (error instanceof z.ZodError) {
+                    throw new createJsonSchemaLlmClient_js_1.SchemaValidationError(error.toString(), { cause: error });
+                }
+                throw error;
+            }
         };
         const result = await jsonSchemaClient.promptJson(messages, schema, {
             ...options,

package/dist/llmFactory.d.ts

@@ -10,27 +10,27 @@ export declare function createLlm(params: CreateLlmFactoryParams): {
     };
     promptJson: <T>(messages: import("openai/resources/index.js").ChatCompletionMessageParam[], schema: Record<string, any>, options?: import("./createJsonSchemaLlmClient.js").JsonSchemaLlmClientOptions) => Promise<T>;
     promptRetry: {
-        <T = import("openai/resources/index.js").ChatCompletion>(content: string, options?: Omit<import("./createLlmRetryClient.js").LlmRetryOptions<T>, "messages">): Promise<T>;
-        <T = import("openai/resources/index.js").ChatCompletion>(options: import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
+        <T = import("openai/resources/index.js").ChatCompletion>(content: string, options?: import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
+        <T = import("openai/resources/index.js").ChatCompletion>(options: import("./createLlmClient.js").LlmPromptOptions & import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
     };
     promptTextRetry: {
-        <T = string>(content: string, options?: Omit<import("./createLlmRetryClient.js").LlmRetryOptions<T>, "messages">): Promise<T>;
-        <T = string>(options: import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
+        <T = string>(content: string, options?: import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
+        <T = string>(options: import("./createLlmClient.js").LlmPromptOptions & import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
     };
     promptImageRetry: {
-        <T = Buffer<ArrayBufferLike>>(content: string, options?: Omit<import("./createLlmRetryClient.js").LlmRetryOptions<T>, "messages">): Promise<T>;
-        <T = Buffer<ArrayBufferLike>>(options: import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
+        <T = Buffer<ArrayBufferLike>>(content: string, options?: import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
+        <T = Buffer<ArrayBufferLike>>(options: import("./createLlmClient.js").LlmPromptOptions & import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
     };
     prompt: {
-        (content: string, options?: Omit<import("./createLlmClient.js").LlmPromptOptions, "messages">): Promise<import("openai/resources/index.js").ChatCompletion>;
+        (content: string, options?: import("./createLlmClient.js").LlmCommonOptions): Promise<import("openai/resources/index.js").ChatCompletion>;
         (options: import("./createLlmClient.js").LlmPromptOptions): Promise<import("openai/resources/index.js").ChatCompletion>;
     };
     promptText: {
-        (content: string, options?: Omit<import("./createLlmClient.js").LlmPromptOptions, "messages">): Promise<string>;
+        (content: string, options?: import("./createLlmClient.js").LlmCommonOptions): Promise<string>;
         (options: import("./createLlmClient.js").LlmPromptOptions): Promise<string>;
     };
     promptImage: {
-        (content: string, options?: Omit<import("./createLlmClient.js").LlmPromptOptions, "messages">): Promise<Buffer>;
+        (content: string, options?: import("./createLlmClient.js").LlmCommonOptions): Promise<Buffer>;
         (options: import("./createLlmClient.js").LlmPromptOptions): Promise<Buffer>;
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-fns",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
     "ajv": "^8.17.1",
     "openai": "^6.9.1",
     "undici": "^7.16.0",
-    "zod": "^4.1.13"
+    "zod": "^4.2.1"
   },
   "devDependencies": {
     "@keyv/sqlite": "^4.0.6",

package/readme.md

@@ -27,6 +27,7 @@ const llm = createLlm({
     // cache: Cache instance (cache-manager)
     // queue: PQueue instance for concurrency control
     // maxConversationChars: number (auto-truncation)
+    // defaultRequestOptions: { headers, timeout, signal }
 });
 ```
 
@@ -214,8 +215,14 @@ const res = await llm.prompt({
     
     // Library Extensions
     model: "gpt-4o",    // Override default model for this call
-    ttl: 5000,          // Cache this specific call for 5s (in ms)
     retries: 5,         // Retry network errors 5 times
+    
+    // Request-level options (headers, timeout, abort signal)
+    requestOptions: {
+        headers: { 'X-Cache-Salt': 'v2' },  // Affects cache key
+        timeout: 60000,
+        signal: abortController.signal
+    }
 });
 ```
 
@@ -299,7 +306,6 @@ const gameState = await llm.promptZod(
         model: "google/gemini-flash-1.5", 
         disableJsonFixer: true, // Turn off the automatic JSON repair agent
         maxRetries: 0,          // Fail immediately on error
-        ttl: 60000              // Cache result
     }
 );
 ```