llm-fns 1.0.2

package/src/createZodLlmClient.spec.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { normalizeZodArgs } from './createZodLlmClient.js';
+
+describe('normalizeZodArgs', () => {
+    const TestSchema = z.object({
+        foo: z.string()
+    });
+
+    it('should normalize Schema Only (Case 1)', () => {
+        const result = normalizeZodArgs(TestSchema);
+        
+        expect(result.mainInstruction).toContain('Generate a valid JSON');
+        expect(result.userMessagePayload).toBe('Generate the data.');
+        expect(result.dataExtractionSchema).toBe(TestSchema);
+        expect(result.options).toBeUndefined();
+    });
+
+    it('should normalize Schema Only with Options (Case 1)', () => {
+        const options = { temperature: 0.5 };
+        const result = normalizeZodArgs(TestSchema, options);
+        
+        expect(result.mainInstruction).toContain('Generate a valid JSON');
+        expect(result.userMessagePayload).toBe('Generate the data.');
+        expect(result.dataExtractionSchema).toBe(TestSchema);
+        expect(result.options).toBe(options);
+    });
+
+    it('should normalize Prompt + Schema (Case 2)', () => {
+        const prompt = "Extract data";
+        const result = normalizeZodArgs(prompt, TestSchema);
+        
+        expect(result.mainInstruction).toContain('You are a helpful assistant');
+        expect(result.userMessagePayload).toBe(prompt);
+        expect(result.dataExtractionSchema).toBe(TestSchema);
+        expect(result.options).toBeUndefined();
+    });
+
+    it('should normalize Prompt + Schema with Options (Case 2)', () => {
+        const prompt = "Extract data";
+        const options = { temperature: 0.5 };
+        const result = normalizeZodArgs(prompt, TestSchema, options);
+        
+        expect(result.mainInstruction).toContain('You are a helpful assistant');
+        expect(result.userMessagePayload).toBe(prompt);
+        expect(result.dataExtractionSchema).toBe(TestSchema);
+        expect(result.options).toBe(options);
+    });
+
+    it('should normalize System + User + Schema (Case 3)', () => {
+        const system = "System prompt";
+        const user = "User prompt";
+        const result = normalizeZodArgs(system, user, TestSchema);
+        
+        expect(result.mainInstruction).toBe(system);
+        expect(result.userMessagePayload).toBe(user);
+        expect(result.dataExtractionSchema).toBe(TestSchema);
+        expect(result.options).toBeUndefined();
+    });
+
+    it('should normalize System + User + Schema with Options (Case 3)', () => {
+        const system = "System prompt";
+        const user = "User prompt";
+        const options = { temperature: 0.5 };
+        const result = normalizeZodArgs(system, user, TestSchema, options);
+        
+        expect(result.mainInstruction).toBe(system);
+        expect(result.userMessagePayload).toBe(user);
+        expect(result.dataExtractionSchema).toBe(TestSchema);
+        expect(result.options).toBe(options);
+    });
+
+    it('should throw error for invalid arguments', () => {
+        expect(() => normalizeZodArgs({} as any)).toThrow('Invalid arguments');
+    });
+});

package/src/createZodLlmClient.ts

@@ -0,0 +1,378 @@
+import OpenAI from 'openai'; // Import the OpenAI library
+import * as z from "zod";
+import { PromptFunction, LlmPromptOptions, OpenRouterResponseFormat, IsPromptCachedFunction } from "./createLlmClient.js";
+import { createLlmRetryClient, LlmRetryError, LlmRetryOptions } from "./createLlmRetryClient.js";
+import { ZodError, ZodTypeAny } from "zod";
+
+export type ZodLlmClientOptions = Omit<LlmPromptOptions, 'messages' | 'response_format'> & {
+    maxRetries?: number;
+    /**
+     * If true, passes `response_format: { type: 'json_object' }` to the model.
+     * If false, only includes the schema in the system prompt.
+     * Defaults to true.
+     */
+    useResponseFormat?: boolean;
+    /**
+     * A hook to process the parsed JSON data before it is validated against the Zod schema.
+     * This can be used to merge partial results or perform other transformations.
+     * @param data The parsed JSON data from the LLM response.
+     * @returns The processed data to be validated.
+     */
+    beforeValidation?: (data: any) => any;
+}
+
+export interface CreateZodLlmClientParams {
+    prompt: PromptFunction;
+    isPromptCached: IsPromptCachedFunction;
+    fallbackPrompt?: PromptFunction;
+    disableJsonFixer?: boolean;
+}
+
+function isZodSchema(obj: any): obj is ZodTypeAny {
+    return (
+        typeof obj === 'object' &&
+        obj !== null &&
+        'parse' in obj &&
+        '_def' in obj
+    );
+}
+
+export interface NormalizedZodArgs<T extends ZodTypeAny> {
+    mainInstruction: string;
+    userMessagePayload: string | OpenAI.Chat.Completions.ChatCompletionContentPart[];
+    dataExtractionSchema: T;
+    options?: ZodLlmClientOptions;
+}
+
+export function normalizeZodArgs<T extends ZodTypeAny>(
+    arg1: string | T,
+    arg2?: string | OpenAI.Chat.Completions.ChatCompletionContentPart[] | T | ZodLlmClientOptions,
+    arg3?: T | ZodLlmClientOptions,
+    arg4?: ZodLlmClientOptions
+): NormalizedZodArgs<T> {
+    if (isZodSchema(arg1)) {
+        // Case 1: promptZod(schema, options?)
+        return {
+            mainInstruction: "Generate a valid JSON object based on the schema.",
+            userMessagePayload: "Generate the data.",
+            dataExtractionSchema: arg1,
+            options: arg2 as ZodLlmClientOptions | undefined
+        };
+    }
+
+    if (typeof arg1 === 'string') {
+        if (isZodSchema(arg2)) {
+            // Case 2: promptZod(prompt, schema, options?)
+            return {
+                mainInstruction: "You are a helpful assistant that outputs JSON matching the provided schema.",
+                userMessagePayload: arg1,
+                dataExtractionSchema: arg2 as T,
+                options: arg3 as ZodLlmClientOptions | undefined
+            };
+        }
+
+        // Case 3: promptZod(system, user, schema, options?)
+        return {
+            mainInstruction: arg1,
+            userMessagePayload: arg2 as string | OpenAI.Chat.Completions.ChatCompletionContentPart[],
+            dataExtractionSchema: arg3 as T,
+            options: arg4
+        };
+    }
+
+    throw new Error("Invalid arguments passed to promptZod");
+}
+
+export function createZodLlmClient(params: CreateZodLlmClientParams) {
+    const { prompt, isPromptCached, fallbackPrompt, disableJsonFixer = false } = params;
+    const llmRetryClient = createLlmRetryClient({ prompt, fallbackPrompt });
+
+    async function _tryToFixJson(
+        brokenResponse: string,
+        schemaJsonString: string,
+        errorDetails: string,
+        options?: ZodLlmClientOptions
+    ): Promise<string | null> {
+        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.
+
+Your task is to act as a JSON fixer. Analyze the provided "BROKEN RESPONSE" and correct it to match the "REQUIRED JSON SCHEMA".
+
+- If the broken response contains all the necessary information to create a valid JSON object according to the schema, please provide the corrected, valid JSON object.
+- If the broken response is missing essential information, or is too garbled to be fixed, please respond with the exact string: "CANNOT_FIX".
+- Your response must be ONLY the corrected JSON object or the string "CANNOT_FIX". Do not include any other text, explanations, or markdown formatting.
+
+REQUIRED JSON SCHEMA:
+${schemaJsonString}
+
+ERROR DETAILS:
+${errorDetails}
+
+BROKEN RESPONSE:
+${brokenResponse}
+`;
+
+        const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+            { role: 'system', content: 'You are an expert at fixing malformed JSON data to match a specific schema.' },
+            { role: 'user', content: fixupPrompt }
+        ];
+
+        const useResponseFormat = options?.useResponseFormat ?? true;
+        const response_format: OpenRouterResponseFormat | undefined = useResponseFormat
+            ? { type: 'json_object' }
+            : undefined;
+
+        const { maxRetries, useResponseFormat: _useResponseFormat, ...restOptions } = options || {};
+
+        const completion = await prompt({
+            messages,
+            response_format,
+            ...restOptions
+        });
+
+        const fixedResponse = completion.choices[0]?.message?.content;
+
+        if (fixedResponse && fixedResponse.trim() === 'CANNOT_FIX') {
+            return null;
+        }
+
+        return fixedResponse || null;
+    }
+
+
+    async function _parseOrFixJson(
+        llmResponseString: string,
+        schemaJsonString: string,
+        options: ZodLlmClientOptions | undefined
+    ): Promise<any> {
+        let jsonDataToParse: string = 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]) {
+            jsonDataToParse = match[1].trim();
+        }
+
+        if (jsonDataToParse === "") {
+            throw new Error("LLM returned an empty string.");
+        }
+
+        try {
+            return JSON.parse(jsonDataToParse);
+        } catch (parseError: any) {
+            if (disableJsonFixer) {
+                throw parseError; // re-throw original error
+            }
+
+            // Attempt a one-time fix before failing.
+            const errorDetails = `JSON Parse Error: ${parseError.message}`;
+            const fixedResponse = await _tryToFixJson(jsonDataToParse, schemaJsonString, errorDetails, options);
+
+            if (fixedResponse) {
+                try {
+                    return JSON.parse(fixedResponse);
+                } catch (e) {
+                    // Fix-up failed, throw original error.
+                    throw parseError;
+                }
+            }
+
+            throw parseError; // if no fixed response
+        }
+    }
+
+    async function _validateOrFixSchema<SchemaType extends ZodTypeAny>(
+        jsonData: any,
+        dataExtractionSchema: SchemaType,
+        schemaJsonString: string,
+        options: ZodLlmClientOptions | undefined
+    ): Promise<z.infer<SchemaType>> {
+        try {
+            if (options?.beforeValidation) {
+                jsonData = options.beforeValidation(jsonData);
+            }
+            return dataExtractionSchema.parse(jsonData);
+        } catch (validationError: any) {
+            if (!(validationError instanceof ZodError) || disableJsonFixer) {
+                throw validationError;
+            }
+
+            // Attempt a one-time fix for schema validation errors.
+            const errorDetails = `Schema Validation Error: ${JSON.stringify(validationError.format(), null, 2)}`;
+            const fixedResponse = await _tryToFixJson(JSON.stringify(jsonData, null, 2), schemaJsonString, errorDetails, options);
+
+            if (fixedResponse) {
+                try {
+                    let fixedJsonData = JSON.parse(fixedResponse);
+                    if (options?.beforeValidation) {
+                        fixedJsonData = options.beforeValidation(fixedJsonData);
+                    }
+                    return dataExtractionSchema.parse(fixedJsonData);
+                } catch (e) {
+                    // Fix-up failed, throw original validation error
+                    throw validationError;
+                }
+            }
+
+            throw validationError; // if no fixed response
+        }
+    }
+
+    function _getZodPromptConfig<T extends ZodTypeAny>(
+        mainInstruction: string,
+        dataExtractionSchema: T,
+        options?: ZodLlmClientOptions
+    ) {
+        const schema = z.toJSONSchema(dataExtractionSchema, {
+            unrepresentable: 'any'
+        })
+        const schemaJsonString = JSON.stringify(schema);
+
+        const commonPromptFooter = `
+Your response MUST be a single JSON entity (object or array) that strictly adheres to the following JSON schema.
+Do NOT include any other text, explanations, or markdown formatting (like \`\`\`json) before or after the JSON entity.
+
+JSON schema:
+${schemaJsonString}`;
+
+        const finalMainInstruction = `${mainInstruction}\n${commonPromptFooter}`;
+
+        const useResponseFormat = options?.useResponseFormat ?? true;
+        const response_format: OpenRouterResponseFormat | undefined = useResponseFormat
+            ? { type: 'json_object' }
+            : undefined;
+
+        return { finalMainInstruction, schemaJsonString, response_format };
+    }
+
+    async function promptZod<T extends ZodTypeAny>(
+        schema: T,
+        options?: ZodLlmClientOptions
+    ): Promise<z.infer<T>>;
+    async function promptZod<T extends ZodTypeAny>(
+        prompt: string,
+        schema: T,
+        options?: ZodLlmClientOptions
+    ): Promise<z.infer<T>>;
+    async function promptZod<T extends ZodTypeAny>(
+        mainInstruction: string,
+        userMessagePayload: string | OpenAI.Chat.Completions.ChatCompletionContentPart[],
+        dataExtractionSchema: T,
+        options?: ZodLlmClientOptions
+    ): Promise<z.infer<T>>;
+    async function promptZod<T extends ZodTypeAny>(
+        arg1: string | T,
+        arg2?: string | OpenAI.Chat.Completions.ChatCompletionContentPart[] | T | ZodLlmClientOptions,
+        arg3?: T | ZodLlmClientOptions,
+        arg4?: ZodLlmClientOptions
+    ): Promise<z.infer<T>> {
+        const { mainInstruction, userMessagePayload, dataExtractionSchema, options } = normalizeZodArgs(arg1, arg2, arg3, arg4);
+
+        const { finalMainInstruction, schemaJsonString, response_format } = _getZodPromptConfig(
+            mainInstruction,
+            dataExtractionSchema,
+            options
+        );
+
+        const processResponse = async (llmResponseString: string): Promise<z.infer<T>> => {
+            let jsonData: any;
+            try {
+                jsonData = await _parseOrFixJson(llmResponseString, schemaJsonString, options);
+            } catch (parseError: any) {
+                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 LlmRetryError(
+                    errorMessage,
+                    'JSON_PARSE_ERROR',
+                    undefined,
+                    llmResponseString
+                );
+            }
+
+            try {
+                const validatedData = await _validateOrFixSchema(jsonData, dataExtractionSchema, schemaJsonString, options);
+                return validatedData;
+            } catch (validationError: any) {
+                if (validationError instanceof ZodError) {
+                    const rawResponseForError = JSON.stringify(jsonData, null, 2);
+                    const errorDetails = JSON.stringify(validationError.format(), null, 2);
+                    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 LlmRetryError(
+                        errorMessage,
+                        'CUSTOM_ERROR',
+                        validationError.format(),
+                        rawResponseForError
+                    );
+                }
+                // For other errors, rethrow and let LlmRetryClient handle as critical.
+                throw validationError;
+            }
+        };
+
+        const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+            { role: "system", content: finalMainInstruction },
+            { role: "user", content: userMessagePayload }
+        ];
+
+        const retryOptions: LlmRetryOptions<z.infer<T>> = {
+            ...options,
+            messages,
+            response_format,
+            validate: processResponse
+        };
+
+        // Use promptTextRetry because we expect a string response to parse as JSON
+        return llmRetryClient.promptTextRetry(retryOptions);
+    }
+
+    async function isPromptZodCached<T extends ZodTypeAny>(
+        schema: T,
+        options?: ZodLlmClientOptions
+    ): Promise<boolean>;
+    async function isPromptZodCached<T extends ZodTypeAny>(
+        prompt: string,
+        schema: T,
+        options?: ZodLlmClientOptions
+    ): Promise<boolean>;
+    async function isPromptZodCached<T extends ZodTypeAny>(
+        mainInstruction: string,
+        userMessagePayload: string | OpenAI.Chat.Completions.ChatCompletionContentPart[],
+        dataExtractionSchema: T,
+        options?: ZodLlmClientOptions
+    ): Promise<boolean>;
+    async function isPromptZodCached<T extends ZodTypeAny>(
+        arg1: string | T,
+        arg2?: string | OpenAI.Chat.Completions.ChatCompletionContentPart[] | T | ZodLlmClientOptions,
+        arg3?: T | ZodLlmClientOptions,
+        arg4?: ZodLlmClientOptions
+    ): Promise<boolean> {
+        const { mainInstruction, userMessagePayload, dataExtractionSchema, options } = normalizeZodArgs(arg1, arg2, arg3, arg4);
+
+        const { finalMainInstruction, response_format } = _getZodPromptConfig(
+            mainInstruction,
+            dataExtractionSchema,
+            options
+        );
+
+        const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+            { role: "system", content: finalMainInstruction },
+            { role: "user", content: userMessagePayload }
+        ];
+
+        const { maxRetries, useResponseFormat: _u, beforeValidation, ...restOptions } = options || {};
+
+        return isPromptCached({
+            messages,
+            response_format,
+            ...restOptions
+        });
+    }
+
+    return { promptZod, isPromptZodCached };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './createLlmClient.js';
+export * from './createLlmRetryClient.js';
+export * from './createZodLlmClient.js';
+export * from './llmFactory.js';
+export * from './retryUtils.js';

package/src/llmFactory.ts

@@ -0,0 +1,26 @@
+import { createLlmClient, CreateLlmClientParams } from "./createLlmClient.js";
+import { createLlmRetryClient } from "./createLlmRetryClient.js";
+import { createZodLlmClient } from "./createZodLlmClient.js";
+
+export interface CreateLlmFactoryParams extends CreateLlmClientParams {
+    // Optional overrides for specific sub-clients if needed, but usually just base params
+}
+
+export function createLlm(params: CreateLlmFactoryParams) {
+    const baseClient = createLlmClient(params);
+    
+    const retryClient = createLlmRetryClient({
+        prompt: baseClient.prompt
+    });
+
+    const zodClient = createZodLlmClient({
+        prompt: baseClient.prompt,
+        isPromptCached: baseClient.isPromptCached
+    });
+
+    return {
+        ...baseClient,
+        ...retryClient,
+        ...zodClient
+    };
+}

package/src/retryUtils.ts

@@ -0,0 +1,91 @@
+// retryUtils.ts
+
+/**
+ * Describes the outcome of a validation/processing step in a retry loop.
+ */
+export interface RetryValidationResult<ValidatedDataType, FeedbackType = any> {
+    isValid: boolean;
+    data?: ValidatedDataType;         // The successfully validated data, if isValid is true.
+    feedbackForNextAttempt?: FeedbackType; // Information to guide the next attempt of the operation.
+    isCriticalFailure?: boolean;      // If true, indicates an unrecoverable error, stopping retries immediately.
+}
+
+/**
+ * Executes an operation with a retry mechanism.
+ *
+ * @param operation - An async function representing the operation to be tried.
+ *                    It receives the current attempt number and feedback from the previous validation.
+ * @param validateAndProcess - An async function that processes the raw result from the operation
+ *                             and validates it. It returns a RetryValidationResult.
+ * @param maxRetries - The maximum number of retries after the initial attempt (e.g., 2 means 3 total attempts).
+ * @param initialFeedbackForOperation - Optional initial feedback to pass to the very first call of the operation.
+ * @param shouldRetryError - Optional function to determine if a specific error should trigger a retry. Returns true to retry, false to throw immediately.
+ * @returns A Promise that resolves with the validated data if successful.
+ * @throws An error if all attempts fail or a critical failure occurs.
+ */
+export async function executeWithRetry<OperationReturnType, ValidatedDataType, FeedbackType = any>(
+    operation: (attemptNumber: number, feedbackForOperation?: FeedbackType) => Promise<OperationReturnType>,
+    validateAndProcess: (
+        rawResult: OperationReturnType,
+        attemptNumber: number
+    ) => Promise<RetryValidationResult<ValidatedDataType, FeedbackType>>,
+    maxRetries: number,
+    initialFeedbackForOperation?: FeedbackType,
+    shouldRetryError?: (error: any) => boolean
+): Promise<ValidatedDataType> {
+    let currentFeedbackForOperation: FeedbackType | undefined = initialFeedbackForOperation;
+
+    for (let attemptNumber = 0; attemptNumber <= maxRetries; attemptNumber++) {
+        if (attemptNumber > 0) {
+            // Exponential backoff with jitter.
+            const baseDelay = 1000; // 1 second
+            const backoffTime = baseDelay * Math.pow(2, attemptNumber - 1);
+            const jitter = backoffTime * (Math.random() * 0.2); // Add up to 20% jitter
+            const totalDelay = backoffTime + jitter;
+            console.log(`Retrying operation... Attempt ${attemptNumber + 1} of ${maxRetries + 1}. Waiting for ${Math.round(totalDelay)}ms.`);
+            await new Promise(resolve => setTimeout(resolve, totalDelay));
+        }
+        let rawResult: OperationReturnType;
+        try {
+            rawResult = await operation(attemptNumber, currentFeedbackForOperation);
+        } catch (opError: any) {
+            // Check if we should stop retrying based on the error type
+            if (shouldRetryError && !shouldRetryError(opError)) {
+                throw opError;
+            }
+
+            // Error directly from the operation (e.g., network failure, `this.ask` throws)
+            if (attemptNumber >= maxRetries) {
+                // On the final attempt, throw an error that preserves the entire causal chain.
+                throw new Error(`Operation failed on final attempt ${attemptNumber + 1}. See cause for details.`, { cause: opError });
+            }
+            // Provide feedback about the operation's own exception for the next attempt
+            currentFeedbackForOperation = {
+                type: 'OPERATION_EXCEPTION', // You'll need to define this in your FeedbackType
+                message: opError.message,
+                rawResponseSnippet: "N/A - Operation threw before producing a response.",
+                // Include the cause's stack if available, otherwise the operation error's stack
+                details: opError.cause?.stack || opError.stack
+            } as unknown as FeedbackType; // Cast as FeedbackType, ensure your type supports this structure
+            continue; // Go to the next attempt
+        }
+
+        const validationOutcome = await validateAndProcess(rawResult, attemptNumber);
+
+        if (validationOutcome.isValid && validationOutcome.data !== undefined) {
+            return validationOutcome.data;
+        }
+
+        currentFeedbackForOperation = validationOutcome.feedbackForNextAttempt;
+
+        if (validationOutcome.isCriticalFailure) {
+            throw new Error(`Critical failure encountered on attempt ${attemptNumber + 1}. Reason: ${JSON.stringify(currentFeedbackForOperation) || 'Unknown critical failure'}`);
+        }
+
+        if (attemptNumber >= maxRetries) {
+            throw new Error(`All ${maxRetries + 1} attempts failed. Last failure reason: ${JSON.stringify(currentFeedbackForOperation)}`);
+        }
+    }
+    // This line should be theoretically unreachable if maxRetries >= 0
+    throw new Error("Exited retry loop unexpectedly. This indicates an issue with the retry logic itself.");
+}

package/tests/basic.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { createTestLlm } from './setup.js';
+import crypto from 'crypto';
+
+describe('Basic LLM Integration', () => {
+    it('should generate text from a simple prompt (Power User Interface)', async () => {
+        const { llm } = await createTestLlm();
+        
+        const response = await llm.promptText({
+            messages: [{ role: 'user', content: 'Say "Hello Integration Test"' }],
+            temperature: 0,
+        });
+
+        expect(response).toBeTruthy();
+        expect(response).toContain('Hello Integration Test');
+    });
+
+    it('should cache responses', async () => {
+        const { llm } = await createTestLlm();
+        const uniqueId = crypto.randomUUID();
+        const promptOptions = {
+            messages: [{ role: 'user', content: `Repeat this ID: ${uniqueId}` }],
+            temperature: 0,
+            ttl: 5000, // 5 seconds
+        };
+
+        // First call - should hit API
+        const start1 = Date.now();
+        const response1 = await llm.promptText(promptOptions);
+        
+        expect(response1).toContain(uniqueId);
+
+        // Check if cached
+        const isCached = await llm.isPromptCached(promptOptions);
+        expect(isCached).toBe(true);
+
+        // Second call - should be fast (cached)
+        const start2 = Date.now();
+        const response2 = await llm.promptText(promptOptions);
+        const duration2 = Date.now() - start2;
+
+        expect(response2).toBe(response1);
+        // API calls usually take > 200ms. Cache hits are usually < 10ms.
+        // We'll be generous and say second call should be significantly faster or under 100ms.
+        expect(duration2).toBeLessThan(100); 
+    });
+});

package/tests/env.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import dotenv from 'dotenv';
+
+// Load .env.test explicitly if available, falling back to .env
+dotenv.config({ path: '.env.test' });
+dotenv.config();
+
+const envSchema = z.object({
+    OPENAI_API_KEY: z.string().min(1, "OPENAI_API_KEY is required"),
+    // Optional override for base URL (e.g. for OpenRouter or local proxies)
+    OPENAI_BASE_URL: z.string().url().optional(),
+    // Model to use for testing. Defaults to a cheaper model.
+    TEST_MODEL: z.string().default("openai/gpt-oss-120b"),
+});
+
+export const env = envSchema.parse(process.env);

package/tests/setup.ts

@@ -0,0 +1,24 @@
+import OpenAI from 'openai';
+import { createCache } from 'cache-manager';
+import KeyvSqlite from '@keyv/sqlite';
+import { createLlm } from '../src/llmFactory.js';
+import { env } from './env.js';
+
+export async function createTestLlm() {
+    const openai = new OpenAI({
+        apiKey: env.OPENAI_API_KEY,
+        baseURL: env.OPENAI_BASE_URL,
+    });
+
+    // Create a SQLite cache for testing
+    const sqliteStore = new KeyvSqlite('sqlite://test-cache.sqlite');
+    const cache = createCache({ stores: [sqliteStore as any] });
+
+    const llm = createLlm({
+        openai,
+        cache,
+        defaultModel: env.TEST_MODEL,
+    });
+
+    return { llm, cache };
+}