llm-fns 1.0.18 → 1.0.19

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,10 @@
 import OpenAI from 'openai';
-import { PromptFunction, LlmPromptOptions } from "./createLlmClient.js";
-export type JsonSchemaLlmClientOptions = Omit<LlmPromptOptions, 'messages' | 'response_format'> & {
+import { PromptFunction, LlmCommonOptions } from "./createLlmClient.js";
+/**
+ * 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 +26,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

@@ -9,7 +9,7 @@ const createLlmRetryClient_js_1 = require("./createLlmRetryClient.js");
 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 +37,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 +51,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]) {
@@ -65,9 +64,8 @@ ${brokenResponse}
         }
         catch (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 +73,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) {
@@ -93,7 +90,6 @@ ${brokenResponse}
             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 +101,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 +115,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 +125,6 @@ ${schemaJsonString}`;
             };
         }
         else {
-            // Prepend new system message
             finalMessages.unshift({
                 role: 'system',
                 content: commonPromptFooter
@@ -146,7 +137,6 @@ ${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);
@@ -180,7 +170,6 @@ The response provided was not valid JSON. Please correct it.`;
                 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.
@@ -190,8 +179,10 @@ The response was valid JSON but did not conform to the required schema. Please r
                 throw new createLlmRetryClient_js_1.LlmRetryError(errorMessage, 'CUSTOM_ERROR', validationError, rawResponseForError);
             }
         };
+        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

@@ -21,12 +21,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 +47,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 +82,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 +96,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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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");
@@ -49,14 +50,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 +88,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 +98,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 +105,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 +131,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 +144,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 +190,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 +213,16 @@ 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);
+                return openai.chat.completions.create(completionParams, requestOptions);
             }, async (completion) => {
                 if (completion.error) {
                     return {
@@ -213,7 +231,6 @@ 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') {
                     return false;
                 }
@@ -225,8 +242,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 +251,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';
@@ -23,26 +23,30 @@ export interface LlmRetryResponseInfo {
     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,8 +27,6 @@ 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;
@@ -45,13 +42,19 @@ class LlmRetryAttemptError extends Error {
     }
 }
 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;
@@ -64,10 +67,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 +112,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);
@@ -129,20 +129,13 @@ function createLlmRetryClient(params) {
             }
             catch (error) {
                 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 });
                 }
                 else {
-                    // This is a non-recoverable error (e.g., network, API key), so we re-throw it immediately.
                     throw error;
                 }
             }
@@ -150,16 +143,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/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.19",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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
     }
 );
 ```