llm-fns 1.0.25 → 1.0.27

package/dist/createCachedFetcher.d.ts

@@ -8,23 +8,19 @@ export type FetcherOptions = RequestInit & {
 };
 export type Fetcher = (url: string | URL | Request, options?: FetcherOptions) => Promise<Response>;
 export interface CreateFetcherDependencies {
-    /** The cache instance (e.g., from cache-manager). */
+    /** Cache instance, for example a cache-manager Cache. */
     cache?: CacheLike;
-    /** A prefix for all cache keys to avoid collisions. Defaults to 'http-cache'. */
+    /** Prefix for all cache keys. Defaults to `http-cache`. */
     prefix?: string;
-    /** Time-to-live for cache entries, in milliseconds. */
+    /** Time-to-live in milliseconds. */
     ttl?: number;
-    /** Request timeout in milliseconds. If not provided, no timeout is applied. */
+    /** Request timeout in milliseconds. */
     timeout?: number;
-    /** User-Agent string for requests. */
+    /** User-Agent header to add to requests. */
     userAgent?: string;
-    /** Optional custom fetch implementation. Defaults to global fetch. */
+    /** Fetch implementation. Defaults to global fetch. */
     fetch?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
-    /**
-     * Optional callback to determine if a response should be cached.
-     * It receives a cloned response that can be read (e.g. .json()).
-     * If it returns false, the response is not cached.
-     */
+    /** Return false to prevent a successful response from being cached. */
     shouldCache?: (response: Response) => Promise<boolean> | boolean;
 }
 export declare class CachedResponse extends Response {
@@ -32,9 +28,5 @@ export declare class CachedResponse extends Response {
     constructor(body: BodyInit | null, init: ResponseInit, finalUrl: string);
     get url(): string;
 }
-/**
- * Factory function that creates a `fetch` replacement with a caching layer.
- * @param deps - Dependencies including the cache instance, prefix, TTL, and timeout.
- * @returns A function with the same signature as native `fetch`.
- */
+/** Creates a fetch-compatible function backed by deterministic response caching. */
 export declare function createCachedFetcher(deps: CreateFetcherDependencies): Fetcher;

package/dist/createCachedFetcher.js

@@ -1,4 +1,4 @@
-import crypto from 'crypto';
+import crypto from 'node:crypto';
 export class CachedResponse extends Response {
     #finalUrl;
     constructor(body, init, finalUrl) {
@@ -9,177 +9,166 @@ export class CachedResponse extends Response {
         return this.#finalUrl;
     }
 }
-/**
- * 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;
+function hashBytes(value) {
+    return crypto.createHash('sha256').update(typeof value === 'string' ? value : Buffer.from(value instanceof ArrayBuffer
+        ? value
+        : value.buffer, value instanceof ArrayBuffer ? undefined : value.byteOffset, value instanceof ArrayBuffer ? undefined : value.byteLength)).digest('hex');
+}
+function normalizedHeaders(headers) {
+    return [...headers.entries()]
+        .map(([name, value]) => {
+        const normalizedName = name.toLowerCase();
+        const normalizedValue = normalizedName === 'content-type' && /^multipart\/form-data\b/iu.test(value)
+            ? 'multipart/form-data'
+            : value.trim();
+        return [normalizedName, normalizedValue];
+    })
+        // Content length and multipart boundaries are transport details, not request semantics.
+        .filter(([name]) => name !== 'content-length')
+        .sort(([left], [right]) => left.localeCompare(right));
+}
+async function hashFormData(formData) {
+    const hash = crypto.createHash('sha256');
+    for (const [name, value] of formData.entries()) {
+        const nameBytes = Buffer.from(name);
+        hash.update(`name:${nameBytes.byteLength}:`);
+        hash.update(nameBytes);
+        if (typeof value === 'string') {
+            const valueBytes = Buffer.from(value);
+            hash.update(`:text:${valueBytes.byteLength}:`);
+            hash.update(valueBytes);
+            continue;
+        }
+        const fileName = 'name' in value && typeof value.name === 'string' ? value.name : '';
+        const metadata = Buffer.from(`${fileName}\0${value.type}`);
+        const bytes = await value.arrayBuffer();
+        hash.update(`:blob:${metadata.byteLength}:`);
+        hash.update(metadata);
+        hash.update(`:${bytes.byteLength}:`);
+        hash.update(Buffer.from(bytes));
     }
-    else {
-        headerEntries = Object.entries(headers);
+    return hash.digest('hex');
+}
+async function hashBody(body) {
+    if (body instanceof FormData)
+        return `form-data:${await hashFormData(body)}`;
+    if (body instanceof URLSearchParams)
+        return `url-search-params:${hashBytes(body.toString())}`;
+    if (typeof body === 'string')
+        return `text:${hashBytes(body)}`;
+    if (body instanceof Blob)
+        return `blob:${body.type}:${hashBytes(await body.arrayBuffer())}`;
+    if (body instanceof ArrayBuffer || ArrayBuffer.isView(body))
+        return `bytes:${hashBytes(body)}`;
+    return `stream:${hashBytes(await new Response(body).arrayBuffer())}`;
+}
+async function hashRequestBody(request) {
+    if (!request.body)
+        return 'none';
+    const clone = request.clone();
+    const contentType = clone.headers.get('content-type') ?? '';
+    if (/^multipart\/form-data\b/iu.test(contentType)) {
+        return `form-data:${await hashFormData(await clone.formData())}`;
     }
-    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.createHash('md5').update(headerString).digest('hex');
+    return `bytes:${hashBytes(await clone.arrayBuffer())}`;
+}
+async function createRequestFingerprint(input, method, headers, body) {
+    const bodyHash = body !== undefined && body !== null
+        ? await hashBody(body)
+        : input instanceof Request
+            ? await hashRequestBody(input)
+            : 'none';
+    return hashBytes(JSON.stringify({
+        version: 2,
+        method: method.toUpperCase(),
+        url: input instanceof Request ? input.url : input.toString(),
+        headers: normalizedHeaders(headers),
+        body: bodyHash,
+    }));
 }
-/**
- * Factory function that creates a `fetch` replacement with a caching layer.
- * @param deps - Dependencies including the cache instance, prefix, TTL, and timeout.
- * @returns A function with the same signature as native `fetch`.
- */
+/** Creates a fetch-compatible function backed by deterministic response caching. */
 export function createCachedFetcher(deps) {
     const { cache, prefix = 'http-cache', ttl, timeout, userAgent, fetch: customFetch, shouldCache } = deps;
     const fetchImpl = customFetch ?? fetch;
-    const fetchWithTimeout = async (url, options) => {
-        const headers = new Headers(options?.headers);
-        if (userAgent) {
-            headers.set('User-Agent', userAgent);
+    return async (input, options) => {
+        const { ttl: requestTtl, ...requestOptions } = options ?? {};
+        const method = requestOptions.method ?? (input instanceof Request ? input.method : 'GET');
+        const headers = new Headers(requestOptions.headers ?? (input instanceof Request ? input.headers : undefined));
+        if (userAgent)
+            headers.set('user-agent', userAgent);
+        let body = requestOptions.body;
+        // Tee streaming bodies so fingerprinting never consumes the copy sent over the network.
+        if (body instanceof ReadableStream) {
+            const [transportBody, fingerprintBody] = body.tee();
+            body = fingerprintBody;
+            requestOptions.body = transportBody;
         }
-        const finalOptions = {
-            ...options,
-            headers,
-        };
-        if (!timeout) {
+        const finalOptions = { ...requestOptions, headers };
+        const urlString = input instanceof Request ? input.url : input.toString();
+        if (!cache)
+            return fetchWithTimeout(fetchImpl, input, finalOptions, timeout, urlString);
+        const fingerprint = await createRequestFingerprint(input, method, headers, body);
+        const cacheKey = `${prefix}:v2:${fingerprint}`;
+        const cachedItem = await cache.get(cacheKey);
+        if (cachedItem) {
+            return new CachedResponse(Buffer.from(cachedItem.bodyBase64, 'base64'), {
+                status: cachedItem.status,
+                headers: cachedItem.headers,
+            }, cachedItem.finalUrl);
+        }
+        const response = await fetchWithTimeout(fetchImpl, input, finalOptions, timeout, urlString);
+        if (!response.ok)
+            return response;
+        let isCacheable = true;
+        if (shouldCache) {
             try {
-                return await fetchImpl(url, finalOptions);
+                isCacheable = await shouldCache(response.clone());
             }
             catch (error) {
-                throw error;
+                console.warn('[Cache Check Error] shouldCache threw an error, skipping cache', error);
+                isCacheable = false;
             }
         }
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => {
-            const urlString = typeof url === 'string' ? url : url.toString();
-            console.log(`[Fetch Timeout] Request timed out after ${timeout}ms for: ${urlString}`);
-            controller.abort();
-        }, timeout);
-        finalOptions.signal = controller.signal;
-        try {
-            const response = await fetchImpl(url, finalOptions);
-            return response;
-        }
-        catch (error) {
-            if (error instanceof Error && error.name === 'AbortError') {
-                const urlString = typeof url === 'string' ? url : url.toString();
-                throw new Error(`Request to ${urlString} timed out after ${timeout}ms`);
-            }
-            throw error;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-    };
-    return async (url, options) => {
-        let method = 'GET';
-        if (options?.method) {
-            method = options.method;
-        }
-        else if (url instanceof Request) {
-            method = url.method;
-        }
-        const urlString = typeof url === 'string' ? url : url.toString();
-        if (!cache) {
-            console.log(`[Cache SKIP] Cache not configured for request to: ${urlString}`);
-            return fetchWithTimeout(url, options);
-        }
-        let cacheKey = `${prefix}:${urlString}`;
-        // Hash body for POST requests
-        if (method.toUpperCase() === 'POST' && options?.body) {
-            let bodyStr = '';
-            if (typeof options.body === 'string') {
-                bodyStr = options.body;
-            }
-            else if (options.body instanceof URLSearchParams) {
-                bodyStr = options.body.toString();
+        else if (response.headers.get('content-type')?.includes('application/json')) {
+            try {
+                const responseBody = await response.clone().json();
+                if (responseBody && typeof responseBody === 'object' && 'error' in responseBody)
+                    isCacheable = false;
             }
-            else {
-                try {
-                    bodyStr = JSON.stringify(options.body);
-                }
-                catch (e) {
-                    bodyStr = 'unserializable';
-                }
+            catch {
+                // A malformed JSON content type does not make an otherwise successful response uncacheable.
             }
-            const bodyHash = crypto.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}`;
+        if (isCacheable) {
+            const bodyBase64 = Buffer.from(await response.clone().arrayBuffer()).toString('base64');
+            await cache.set(cacheKey, {
+                bodyBase64,
+                headers: Object.fromEntries(response.headers.entries()),
+                status: response.status,
+                finalUrl: response.url,
+            }, requestTtl ?? ttl);
         }
-        // 1. Check the cache
-        const cachedItem = await cache.get(cacheKey);
-        if (cachedItem) {
-            const body = Buffer.from(cachedItem.bodyBase64, 'base64');
-            return new CachedResponse(body, {
-                status: cachedItem.status,
-                headers: cachedItem.headers,
-            }, cachedItem.finalUrl);
-        }
-        // 2. Perform the actual fetch if not in cache
-        const fetchAndCache = async () => {
-            const response = await fetchWithTimeout(url, options);
-            // 3. Store in cache on success
-            if (response.ok) {
-                let isCacheable = true;
-                if (shouldCache) {
-                    const checkClone = response.clone();
-                    try {
-                        isCacheable = await shouldCache(checkClone);
-                    }
-                    catch (e) {
-                        console.warn('[Cache Check Error] shouldCache threw an error, skipping cache', e);
-                        isCacheable = false;
-                    }
-                }
-                else {
-                    const contentType = response.headers.get('content-type');
-                    if (contentType && contentType.includes('application/json')) {
-                        const checkClone = response.clone();
-                        try {
-                            const body = await checkClone.json();
-                            if (body && typeof body === 'object' && 'error' in body) {
-                                console.log(`[Cache SKIP] JSON response contains .error property for: ${urlString}`);
-                                isCacheable = false;
-                            }
-                        }
-                        catch (e) {
-                            // Ignore JSON parse errors, assume cacheable if status is OK
-                        }
-                    }
-                }
-                if (isCacheable) {
-                    const responseClone = response.clone();
-                    const bodyBuffer = await responseClone.arrayBuffer();
-                    const bodyBase64 = Buffer.from(bodyBuffer).toString('base64');
-                    const headers = Object.fromEntries(response.headers.entries());
-                    const itemToCache = {
-                        bodyBase64,
-                        headers,
-                        status: response.status,
-                        finalUrl: response.url,
-                    };
-                    await cache.set(cacheKey, itemToCache, options?.ttl ?? ttl);
-                    console.log(`[Cache SET] for: ${cacheKey}`);
-                }
-            }
-            // 4. Return the original response
-            return response;
-        };
-        return fetchAndCache();
+        return response;
     };
 }
+async function fetchWithTimeout(fetchImpl, input, options, timeout, urlString) {
+    if (!timeout)
+        return fetchImpl(input, options);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, controller.signal])
+        : controller.signal;
+    try {
+        return await fetchImpl(input, { ...options, signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted && !options.signal?.aborted) {
+            throw new Error(`Request to ${urlString} timed out after ${timeout}ms`, { cause: error });
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/createCachedFetcher.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/createCachedFetcher.spec.js

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest';
+import OpenAI, { toFile } from 'openai';
+import { createCachedFetcher } from './createCachedFetcher.js';
+function createMemoryCache() {
+    const values = new Map();
+    const cache = {
+        get: async (key) => values.get(key),
+        set: async (key, value) => { values.set(key, value); },
+    };
+    return { cache, values };
+}
+describe('createCachedFetcher', () => {
+    it('caches equivalent multipart requests and distinguishes file contents', async () => {
+        const { cache } = createMemoryCache();
+        const transport = vi.fn(async (_input, init) => {
+            const data = init?.body;
+            return Response.json({ file: await data.get('file').text() });
+        });
+        const cachedFetch = createCachedFetcher({ cache, fetch: transport });
+        const request = (contents) => {
+            const data = new FormData();
+            data.append('model', 'scribe');
+            data.append('file', new Blob([contents], { type: 'audio/flac' }), 'sample.flac');
+            return cachedFetch('https://speech.example/transcriptions', { method: 'POST', body: data });
+        };
+        expect(await (await request('first audio')).json()).toEqual({ file: 'first audio' });
+        expect(await (await request('first audio')).json()).toEqual({ file: 'first audio' });
+        expect(await (await request('different audio')).json()).toEqual({ file: 'different audio' });
+        expect(transport).toHaveBeenCalledTimes(2);
+    });
+    it('fingerprints bodies supplied by Request objects without consuming them', async () => {
+        const { cache } = createMemoryCache();
+        const transport = vi.fn(async (input) => Response.json({ body: await input.text() }));
+        const cachedFetch = createCachedFetcher({ cache, fetch: transport });
+        const makeRequest = (body) => new Request('https://example.test/items', {
+            method: 'PUT', body, headers: { authorization: 'Bearer secret' },
+        });
+        expect(await (await cachedFetch(makeRequest('one'))).json()).toEqual({ body: 'one' });
+        expect(await (await cachedFetch(makeRequest('one'))).json()).toEqual({ body: 'one' });
+        expect(await (await cachedFetch(makeRequest('two'))).json()).toEqual({ body: 'two' });
+        expect(transport).toHaveBeenCalledTimes(2);
+    });
+    it('keeps credentials opaque while separating requests with different headers', async () => {
+        const { cache, values } = createMemoryCache();
+        const transport = vi.fn(async () => Response.json({ ok: true }));
+        const cachedFetch = createCachedFetcher({ cache, prefix: 'test', fetch: transport });
+        await cachedFetch('https://example.test', { headers: { authorization: 'Bearer first-secret' } });
+        await cachedFetch('https://example.test', { headers: { authorization: 'Bearer second-secret' } });
+        expect(transport).toHaveBeenCalledTimes(2);
+        expect([...values.keys()].join('\n')).not.toContain('secret');
+    });
+    it('preserves a streaming request body after hashing it', async () => {
+        const { cache } = createMemoryCache();
+        const transport = vi.fn(async (_input, init) => Response.json({ body: await new Response(init?.body).text() }));
+        const cachedFetch = createCachedFetcher({ cache, fetch: transport });
+        const stream = new Blob(['stream contents']).stream();
+        expect(await (await cachedFetch('https://example.test/upload', {
+            method: 'POST', body: stream, duplex: 'half',
+        })).json()).toEqual({ body: 'stream contents' });
+    });
+    it('caches multipart uploads produced by the OpenAI SDK', async () => {
+        const { cache } = createMemoryCache();
+        const transport = vi.fn(async (input) => {
+            if (input.toString() === 'data:,')
+                return new Response();
+            return Response.json({ words: [] });
+        });
+        const client = new OpenAI({
+            apiKey: 'test-key',
+            fetch: createCachedFetcher({ cache, fetch: transport }),
+        });
+        const transcribe = async (contents) => client.audio.transcriptions.create({
+            file: await toFile(Buffer.from(contents), 'sample.flac'),
+            model: 'whisper-1',
+            response_format: 'verbose_json',
+        });
+        await transcribe('same audio');
+        await transcribe('same audio');
+        await transcribe('different audio');
+        const apiCalls = transport.mock.calls.filter(([input]) => input.toString().startsWith('https://'));
+        expect(apiCalls).toHaveLength(2);
+    });
+});

package/dist/createCandidateSelector.js

@@ -1,7 +1,6 @@
-import crypto from 'crypto';
 export function createCandidateSelector(params) {
     const { candidateCount, generate, judge, onCandidateError } = params;
-    async function run(input, baseSalt = crypto.randomUUID()) {
+    async function run(input, baseSalt = 'candidate') {
         // 1. Generate Candidates in Parallel
         const promises = [];
         for (let i = 0; i < candidateCount; i++) {

package/dist/createLlmClient.d.ts

@@ -23,6 +23,7 @@ export type OpenRouterResponseFormat = {
         schema: object;
     };
 };
+export type LlmAudioTransport = 'auto' | 'chat' | 'chat-stream';
 /**
  * Request-level options passed to the OpenAI SDK.
  * These are separate from the body parameters.
@@ -49,6 +50,12 @@ export interface LlmCommonOptions {
     response_format?: OpenRouterResponseFormat;
     modalities?: string[];
     audio?: OpenAI.Chat.Completions.ChatCompletionAudioParam;
+    /**
+     * Selects how audio output is requested. `auto` prefers streaming because
+     * OpenRouter audio output requires it, then falls back to non-streaming chat
+     * if streaming is rejected by the provider.
+     */
+    audioTransport?: LlmAudioTransport;
     image_config?: {
         aspect_ratio?: string;
     };
@@ -64,6 +71,7 @@ export interface LlmCommonOptions {
     user?: string;
     tools?: OpenAI.Chat.Completions.ChatCompletionTool[];
     tool_choice?: OpenAI.Chat.Completions.ChatCompletionToolChoiceOption;
+    stream_options?: OpenAI.Chat.Completions.ChatCompletionStreamOptions;
 }
 /**
  * Options for the individual "prompt" function calls.
@@ -119,8 +127,13 @@ export declare function createLlmClient(params: CreateLlmClientParams): {
         (content: string, options?: LlmCommonOptions): Promise<Buffer>;
         (options: LlmPromptOptions): Promise<Buffer>;
     };
+    promptAudioStream: {
+        (content: string, options?: LlmCommonOptions): AsyncIterable<Buffer>;
+        (options: LlmPromptOptions): AsyncIterable<Buffer>;
+    };
 };
 export type PromptFunction = ReturnType<typeof createLlmClient>['prompt'];
 export type PromptTextFunction = ReturnType<typeof createLlmClient>['promptText'];
 export type PromptImageFunction = ReturnType<typeof createLlmClient>['promptImage'];
 export type PromptAudioFunction = ReturnType<typeof createLlmClient>['promptAudio'];
+export type PromptAudioStreamFunction = ReturnType<typeof createLlmClient>['promptAudioStream'];

package/dist/createLlmClient.js

@@ -1,6 +1,6 @@
 import { executeWithRetry } from './retryUtils.js';
 import { truncateMessages, getPromptSummary } from './util.js';
-import { extractImageBuffer, extractAudioBuffer } from './extractBinary.js';
+import { extractImageBuffer, extractAudioBuffer, extractAudioDeltaData } from './extractBinary.js';
 import { createDnsFetcher } from './createDnsFetcher.js';
 export class LlmFatalError extends Error {
     cause;
@@ -63,8 +63,47 @@ export function normalizeOptions(arg1, arg2) {
 export function createLlmClient(params) {
     const { openai, defaultModel: factoryDefaultModel, maxConversationChars, queue, defaultRequestOptions, retryBaseDelay: factoryRetryBaseDelay = 1000, fetch: factoryFetch } = params;
     const fetchImpl = factoryFetch ?? createDnsFetcher();
+    const getErrorMessage = (error) => [
+        error?.message,
+        error?.cause?.message,
+        error?.error?.message,
+        error?.cause?.error?.message,
+        error?.response?.data?.error?.message
+    ].filter(Boolean).join('\n');
+    const isStreamingUnsupportedError = (error) => {
+        const message = getErrorMessage(error);
+        return /stream(ing)?\s+(is\s+)?not\s+supported|does\s+not\s+support\s+stream|stream\s+unsupported/i.test(message);
+    };
+    const withAudioOutputDefaults = (promptParams, defaultFormat) => {
+        const factoryModelConfig = typeof factoryDefaultModel === 'object' && factoryDefaultModel !== null
+            ? factoryDefaultModel
+            : {};
+        const callModelConfig = typeof promptParams.model === 'object' && promptParams.model !== null
+            ? promptParams.model
+            : {};
+        const nextModalities = [
+            ...(factoryModelConfig.modalities ?? []),
+            ...(callModelConfig.modalities ?? []),
+            ...(promptParams.modalities ?? [])
+        ];
+        if (!nextModalities.includes('text'))
+            nextModalities.push('text');
+        if (!nextModalities.includes('audio'))
+            nextModalities.push('audio');
+        return {
+            ...promptParams,
+            modalities: [...new Set(nextModalities)],
+            audio: {
+                voice: 'alloy',
+                format: defaultFormat,
+                ...(factoryModelConfig.audio ?? {}),
+                ...(callModelConfig.audio ?? {}),
+                ...(promptParams.audio ?? {})
+            }
+        };
+    };
     const getCompletionParams = (promptParams) => {
-        const { model: callSpecificModel, messages, retries, retryBaseDelay: callSpecificRetryBaseDelay, requestOptions, ...restApiOptions } = promptParams;
+        const { model: callSpecificModel, messages, retries, retryBaseDelay: callSpecificRetryBaseDelay, requestOptions, audioTransport: _audioTransport, ...restApiOptions } = promptParams;
         const finalMessages = maxConversationChars
             ? truncateMessages(messages, maxConversationChars)
             : messages;
@@ -146,11 +185,115 @@ export function createLlmClient(params) {
         return extractImageBuffer(response, fetchImpl);
     }
     async function promptAudio(arg1, arg2) {
-        const promptParams = normalizeOptions(arg1, arg2);
-        // Ensure modalities includes audio if not explicitly set, though user should ideally provide it.
-        // We won't force it here to avoid overriding user intent, but promptAudio implies audio output.
-        const response = await prompt(promptParams);
-        return extractAudioBuffer(response);
+        const normalizedParams = normalizeOptions(arg1, arg2);
+        const transport = normalizedParams.audioTransport ?? 'auto';
+        if (transport === 'chat') {
+            const response = await prompt(withAudioOutputDefaults(normalizedParams, 'mp3'));
+            return extractAudioBuffer(response);
+        }
+        const streamParams = withAudioOutputDefaults(normalizedParams, 'pcm16');
+        try {
+            return await promptAudioViaChatStream(streamParams);
+        }
+        catch (error) {
+            if (transport === 'auto' && isStreamingUnsupportedError(error)) {
+                const response = await prompt(withAudioOutputDefaults(normalizedParams, 'mp3'));
+                return extractAudioBuffer(response);
+            }
+            throw error;
+        }
+    }
+    async function* promptAudioStream(arg1, arg2) {
+        const promptParams = withAudioOutputDefaults(normalizeOptions(arg1, arg2), 'pcm16');
+        const { completionParams, finalMessages, retries, requestOptions, retryBaseDelay: baseDelay } = getCompletionParams(promptParams);
+        const promptSummary = getPromptSummary(finalMessages);
+        const streamParams = {
+            ...completionParams,
+            stream: true
+        };
+        const streamEvents = [];
+        let wakeConsumer;
+        const pushStreamEvent = (event) => {
+            streamEvents.push(event);
+            wakeConsumer?.();
+            wakeConsumer = undefined;
+        };
+        const nextStreamEvent = async () => {
+            while (streamEvents.length === 0) {
+                await new Promise(resolve => {
+                    wakeConsumer = resolve;
+                });
+            }
+            return streamEvents.shift();
+        };
+        let emittedChunkCount = 0;
+        async function readStream() {
+            let chunkCount = 0;
+            try {
+                const stream = await openai.chat.completions.create(streamParams, requestOptions);
+                for await (const chunk of stream) {
+                    const audioData = extractAudioDeltaData(chunk);
+                    if (audioData) {
+                        chunkCount += 1;
+                        emittedChunkCount += 1;
+                        pushStreamEvent({ type: 'chunk', chunk: Buffer.from(audioData, 'base64') });
+                    }
+                }
+                return chunkCount;
+            }
+            catch (error) {
+                if (error?.status === 400 || error?.status === 401 || error?.status === 403) {
+                    throw new LlmFatalError(error.message || 'Fatal API Error', error, finalMessages);
+                }
+                throw error;
+            }
+        }
+        const task = () => executeWithRetry(() => readStream(), async (chunkCount) => {
+            if (chunkCount === 0) {
+                return {
+                    isValid: false,
+                    feedbackForNextAttempt: {
+                        type: 'EMPTY_AUDIO_STREAM',
+                        message: 'LLM returned no streamed audio content.'
+                    }
+                };
+            }
+            return { isValid: true, data: chunkCount };
+        }, retries ?? 3, undefined, (error) => {
+            if (emittedChunkCount > 0)
+                return false;
+            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;
+        }, baseDelay);
+        const producer = (queue
+            ? queue.add(task, { id: promptSummary, messages: finalMessages })
+            : task());
+        producer
+            .then(() => pushStreamEvent({ type: 'done' }))
+            .catch(error => pushStreamEvent({ type: 'error', error }));
+        while (true) {
+            const event = await nextStreamEvent();
+            if (event.type === 'chunk') {
+                yield event.chunk;
+            }
+            else if (event.type === 'error') {
+                throw event.error;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    async function promptAudioViaChatStream(promptParams) {
+        const chunks = [];
+        for await (const chunk of promptAudioStream(promptParams)) {
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks);
     }
-    return { prompt, promptText, promptImage, promptAudio };
+    return { prompt, promptText, promptImage, promptAudio, promptAudioStream };
 }

package/dist/createLlmRetryClient.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { PromptFunction, LlmCommonOptions, LlmPromptOptions } from "./createLlmClient.js";
+import { PromptFunction, PromptAudioFunction, LlmCommonOptions, LlmPromptOptions } from "./createLlmClient.js";
 import { ConversationState } from './createConversation.js';
 export declare class LlmRetryError extends Error {
     readonly message: string;
@@ -38,6 +38,7 @@ export interface LlmRetryOptions<T = any> extends LlmCommonOptions {
 }
 export interface CreateLlmRetryClientParams {
     prompt: PromptFunction;
+    promptAudio?: PromptAudioFunction;
     fallbackPrompt?: PromptFunction;
     retryBaseDelay?: number;
     /** Optional custom fetch implementation for binary extraction */

package/dist/createLlmRetryClient.js

@@ -68,7 +68,7 @@ function constructLlmMessages(initialMessages, attemptNumber, previousError) {
     return messages;
 }
 export function createLlmRetryClient(params) {
-    const { prompt, fallbackPrompt, retryBaseDelay: factoryRetryBaseDelay = 0, fetch: factoryFetch } = params;
+    const { prompt, promptAudio, fallbackPrompt, retryBaseDelay: factoryRetryBaseDelay = 0, fetch: factoryFetch } = params;
     const fetchImpl = factoryFetch ?? createDnsFetcher();
     async function runPromptLoop(retryParams) {
         const { maxRetries = 3, validate, messages: initialMessages, retryBaseDelay = factoryRetryBaseDelay, state, ...restOptions } = retryParams;
@@ -192,6 +192,13 @@ export function createLlmRetryClient(params) {
     async function promptAudioRetry(arg1, arg2) {
         const retryParams = normalizeRetryOptions(arg1, arg2);
         const userValidate = retryParams.validate;
+        if (promptAudio && !userValidate && !retryParams.state && !fallbackPrompt) {
+            const { maxRetries, validate, state, ...promptOptions } = retryParams;
+            return await promptAudio({
+                ...promptOptions,
+                retries: maxRetries ?? promptOptions.retries
+            });
+        }
         retryParams.validate = async (completion, info) => {
             try {
                 const buffer = extractAudioBuffer(completion);

package/dist/extractBinary.d.ts

@@ -19,3 +19,10 @@ export declare function extractImageBuffer(completion: OpenAI.Chat.Completions.C
  * Extracts an audio buffer from a ChatCompletion.
  */
 export declare function extractAudioBuffer(completion: OpenAI.Chat.Completions.ChatCompletion): Buffer;
+/**
+ * Extracts Base64 audio payloads from streamed Chat Completion chunks.
+ * OpenRouter delivers audio output at `choices[0].delta.audio.data`.
+ * Some OpenAI-compatible providers may use adjacent fields, so this accepts the
+ * common variants without widening the public client API.
+ */
+export declare function extractAudioDeltaData(chunk: unknown): string | undefined;

package/dist/extractBinary.js

@@ -18,7 +18,7 @@ export function isAudioResponse(completion) {
     if (message?.audio)
         return true;
     if (Array.isArray(message?.content)) {
-        return message.content.some((part) => part.type === 'input_audio');
+        return message.content.some((part) => part.type === 'input_audio' || part.type === 'audio');
     }
     return false;
 }
@@ -66,11 +66,30 @@ export function extractAudioBuffer(completion) {
     }
     // 2. Check standard content parts
     else if (Array.isArray(message?.content)) {
-        const part = message.content.find((p) => p.type === 'input_audio');
-        audioData = part?.input_audio?.data;
+        const part = message.content.find((p) => p.type === 'input_audio' || p.type === 'audio');
+        audioData = part?.input_audio?.data || part?.audio?.data || part?.data;
     }
     if (audioData) {
         return Buffer.from(audioData, 'base64');
     }
     throw new Error("LLM returned no audio content.");
 }
+/**
+ * Extracts Base64 audio payloads from streamed Chat Completion chunks.
+ * OpenRouter delivers audio output at `choices[0].delta.audio.data`.
+ * Some OpenAI-compatible providers may use adjacent fields, so this accepts the
+ * common variants without widening the public client API.
+ */
+export function extractAudioDeltaData(chunk) {
+    const delta = chunk?.choices?.[0]?.delta;
+    const audio = delta?.audio || delta?.output_audio;
+    if (typeof audio === 'string')
+        return audio;
+    if (audio?.data)
+        return audio.data;
+    if (audio?.delta)
+        return audio.delta;
+    if (delta?.audio_data)
+        return delta.audio_data;
+    return undefined;
+}

package/dist/llmFactory.d.ts

@@ -47,5 +47,9 @@ export declare function createLlm(params: CreateLlmFactoryParams): {
         (content: string, options?: import("./createLlmClient.js").LlmCommonOptions): Promise<Buffer>;
         (options: import("./createLlmClient.js").LlmPromptOptions): Promise<Buffer>;
     };
+    promptAudioStream: {
+        (content: string, options?: import("./createLlmClient.js").LlmCommonOptions): AsyncIterable<Buffer>;
+        (options: import("./createLlmClient.js").LlmPromptOptions): AsyncIterable<Buffer>;
+    };
 };
 export type LlmClient = ReturnType<typeof createLlm>;

package/dist/llmFactory.js

@@ -7,6 +7,7 @@ export function createLlm(params) {
     const baseClient = createLlmClient(params);
     const retryClient = createLlmRetryClient({
         prompt: baseClient.prompt,
+        promptAudio: baseClient.promptAudio,
         retryBaseDelay: params.retryBaseDelay,
         fetch: params.fetch
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-fns",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,9 +8,16 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "test": "vitest run",
+    "release": "scripts/release.sh",
+    "build": "tsc",
+    "watch": "tsc -b -w"
+  },
   "keywords": [],
   "author": "",
   "license": "MIT",
+  "packageManager": "pnpm@10.6.5",
   "dependencies": {
     "ajv": "^8.17.1",
     "openai": "^6.15.0",
@@ -26,11 +33,5 @@
     "p-queue": "^9.0.1",
     "typescript": "^5.9.3",
     "vitest": "^1.6.1"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "release": "scripts/release.sh",
-    "build": "tsc",
-    "watch": "tsc -b -w"
   }
-}
+}

package/readme.md

@@ -10,6 +10,28 @@ Designed for power users who need to switch between simple string prompts and co
 npm install openai zod cache-manager p-queue ajv
 ```
 
+## Cached Fetch
+
+`createCachedFetcher` is a fetch-compatible response cache that can be injected into SDKs such as OpenAI:
+
+```typescript
+import OpenAI from 'openai';
+import { createCachedFetcher } from 'llm-fns';
+
+const cachedFetch = createCachedFetcher({
+    cache,
+    fetch: globalThis.fetch,
+    prefix: 'openai',
+    ttl: 24 * 60 * 60 * 1000,
+});
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, fetch: cachedFetch });
+```
+
+Cache keys fingerprint the effective method, URL, normalized headers, and body. Standard Fetch bodies are supported, including strings, binary data, blobs, streams, `Request` bodies, URL-encoded forms, and multipart `FormData` with file contents. Multipart boundaries and content length are ignored because they are transport details; file bytes, filenames, media types, and form fields remain part of the fingerprint. Header values, including credentials, affect the fingerprint but are never written into the cache key in plain text.
+
+The cache-key format is versioned. Version 1.0.27 intentionally does not read entries created by older releases.
+
 ## Quick Start (Factory)
 
 The `createLlm` factory bundles all functionality (Basic, Retry, Zod) into a single client.
@@ -22,7 +44,7 @@ const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
 const llm = createLlm({
     openai,
-    defaultModel: 'google/gemini-3-pro-preview',
+    defaultModel: '~google/gemini-pro-latest',
     // optional: 
     // cache: Cache instance (cache-manager)
     // queue: PQueue instance for concurrency control
@@ -251,7 +273,50 @@ const buffer2 = await llm.promptImage({
 
 ---
 
-# Use Case 3: Structured Data (`llm.promptJson` & `llm.promptZod`)
+# Use Case 3: Audio (`llm.promptAudio` / `llm.promptAudioStream`)
+
+Generates audio and returns it as a `Buffer`, or yields audio chunks as they arrive. This supports providers that only expose audio output through streaming Chat Completions, including OpenRouter routes to audio-capable OpenAI models.
+
+**Return Type:** `Promise<Buffer>` for `promptAudio`, `AsyncIterable<Buffer>` for `promptAudioStream`
+
+```typescript
+import fs from 'node:fs/promises';
+
+const audio = await llm.promptAudio({
+    model: 'openai/gpt-audio-mini',
+    messages: 'Say exactly: BatchPrompt audio test.',
+    modalities: ['text', 'audio'],
+    audio: {
+        voice: 'alloy',
+        format: 'pcm16'
+    },
+    audioTransport: 'chat-stream'
+});
+
+await fs.writeFile('batchprompt-audio-test.pcm', audio);
+```
+
+For callers that want to process chunks as they arrive, use `promptAudioStream`:
+
+```typescript
+const chunks: Buffer[] = [];
+
+for await (const chunk of llm.promptAudioStream({
+    model: 'openai/gpt-audio-mini',
+    messages: 'Read this sentence aloud.',
+    audio: { voice: 'alloy', format: 'pcm16' }
+})) {
+    chunks.push(chunk);
+}
+
+await fs.writeFile('streamed-audio.pcm', Buffer.concat(chunks));
+```
+
+`promptAudio` defaults to streaming transport because some providers require it for audio output. When streaming, the default audio format is `pcm16`; OpenAI rejects `mp3` for streamed `gpt-audio-mini` responses. If you need non-streaming Chat Completions audio, pass `audioTransport: 'chat'`, where the default format is `mp3`.
+
+---
+
+# Use Case 4: Structured Data (`llm.promptJson` & `llm.promptZod`)
 
 This is a high-level wrapper that employs a **Re-asking Loop**. If the LLM outputs invalid JSON or data that fails the schema validation, the client automatically feeds the error back to the LLM and asks it to fix it (up to `maxRetries`).
 
@@ -303,7 +368,7 @@ const gameState = await llm.promptZod(
     history,             // Arg 1: Context
     GameStateSchema,     // Arg 2: Schema
     {                    // Arg 3: Options Override
-        model: "google/gemini-flash-1.5", 
+        model: "~google/gemini-flash-latest",
         disableJsonFixer: true, // Turn off the automatic JSON repair agent
         maxRetries: 0,          // Fail immediately on error
     }
@@ -392,7 +457,7 @@ const SafeSchema = z.object({
 
 ---
 
-# Use Case 4: Agentic Retry Loops (`llm.promptTextRetry`)
+# Use Case 5: Agentic Retry Loops (`llm.promptTextRetry`)
 
 The library exposes the "Conversational Retry" engine used internally by `promptZod`. You can provide a `validate` function. If it throws a `LlmRetryError`, the error message is fed back to the LLM, and it tries again.
 
@@ -420,7 +485,7 @@ const poem = await llm.promptTextRetry({
 
 ---
 
-# Use Case 5: Iterative Refinement (`createIterativeRefiner`)
+# Use Case 6: Iterative Refinement (`createIterativeRefiner`)
 
 For complex tasks where an LLM needs to "try, check, and fix" its own output (like code generation or complex configuration), use the `IterativeRefiner`.
 
@@ -615,7 +680,7 @@ function getAllResponses(error: LlmRetryExhaustedError): string[] {
 
 ---
 
-# Use Case 6: Architecture & Composition
+# Use Case 7: Architecture & Composition
 
 How to build the client manually to enable **Fallback Chains** and **Smart Routing**.
 
@@ -628,13 +693,13 @@ import { createLlmClient } from './src';
 // 1. Define a CHEAP model
 const cheapClient = createLlmClient({ 
     openai, 
-    defaultModel: 'google/gemini-flash-1.5' 
+    defaultModel: '~google/gemini-flash-latest'
 });
 
 // 2. Define a STRONG model
 const strongClient = createLlmClient({ 
     openai, 
-    defaultModel: 'google/gemini-3-pro-preview' 
+    defaultModel: '~google/gemini-pro-latest'
 });
 ```