@jaypie/llm 1.1.6 → 1.1.8

package/dist/index.js

@@ -1,10 +1,10 @@
-import { BadGatewayError, NotImplementedError, ConfigurationError as ConfigurationError$1 } from '@jaypie/errors';
-import { log, JAYPIE, ConfigurationError, placeholders, sleep } from '@jaypie/core';
+import { ConfigurationError, BadGatewayError, TooManyRequestsError, NotImplementedError } from '@jaypie/errors';
+import { placeholders, log as log$1, JAYPIE, sleep, ConfigurationError as ConfigurationError$1 } from '@jaypie/core';
 import { OpenAI, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, APIConnectionError, APIConnectionTimeoutError, InternalServerError } from 'openai';
 import { zodResponseFormat } from 'openai/helpers/zod';
 import { z } from 'zod';
-import { getEnvSecret } from '@jaypie/aws';
 import RandomLib from 'random';
+import { getEnvSecret } from '@jaypie/aws';
 import { fetchWeatherApi } from 'openmeteo';
 
 const PROVIDER = {
@@ -44,6 +44,171 @@ var constants = /*#__PURE__*/Object.freeze({
     PROVIDER: PROVIDER
 });
 
+const DEFAULT_TOOL_TYPE = "function";
+class Toolkit {
+    constructor(tools, options) {
+        this._tools = tools;
+        this._options = options || {};
+        this.explain = this._options.explain ? true : false;
+    }
+    get tools() {
+        return this._tools.map((tool) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const toolCopy = { ...tool };
+            delete toolCopy.call;
+            if (this.explain && toolCopy.parameters?.type === "object") {
+                if (toolCopy.parameters?.properties) {
+                    if (!toolCopy.parameters.properties.__Explanation) {
+                        toolCopy.parameters.properties.__Explanation = {
+                            type: "string",
+                            description: "Explain the reasoning behind this function call. What is the expected result? Describe possible next steps and the conditions under which they should be taken.",
+                        };
+                    }
+                }
+            }
+            // Set default type if not provided
+            if (!toolCopy.type) {
+                toolCopy.type = DEFAULT_TOOL_TYPE;
+            }
+            return toolCopy;
+        });
+    }
+    async call({ name, arguments: args }) {
+        const tool = this._tools.find((t) => t.name === name);
+        if (!tool) {
+            throw new Error(`Tool '${name}' not found`);
+        }
+        let parsedArgs;
+        try {
+            parsedArgs = JSON.parse(args);
+            if (this.explain) {
+                delete parsedArgs.__Explanation;
+            }
+        }
+        catch {
+            parsedArgs = args;
+        }
+        const result = tool.call(parsedArgs);
+        if (result instanceof Promise) {
+            return await result;
+        }
+        return result;
+    }
+}
+
+// Enums
+var LlmMessageRole;
+(function (LlmMessageRole) {
+    LlmMessageRole["Assistant"] = "assistant";
+    LlmMessageRole["Developer"] = "developer";
+    LlmMessageRole["System"] = "system";
+    LlmMessageRole["User"] = "user";
+})(LlmMessageRole || (LlmMessageRole = {}));
+var LlmMessageType;
+(function (LlmMessageType) {
+    LlmMessageType["FunctionCall"] = "function_call";
+    LlmMessageType["FunctionCallOutput"] = "function_call_output";
+    LlmMessageType["InputFile"] = "input_file";
+    LlmMessageType["InputImage"] = "input_image";
+    LlmMessageType["InputText"] = "input_text";
+    LlmMessageType["ItemReference"] = "item_reference";
+    LlmMessageType["Message"] = "message";
+    LlmMessageType["OutputText"] = "output_text";
+    LlmMessageType["Refusal"] = "refusal";
+})(LlmMessageType || (LlmMessageType = {}));
+var LlmResponseStatus;
+(function (LlmResponseStatus) {
+    LlmResponseStatus["Completed"] = "completed";
+    LlmResponseStatus["Incomplete"] = "incomplete";
+    LlmResponseStatus["InProgress"] = "in_progress";
+})(LlmResponseStatus || (LlmResponseStatus = {}));
+
+/**
+ * Converts a string to a standardized LlmInputMessage
+ * @param input - String to format
+ * @param options - Optional configuration
+ * @param options.data - Data to use for placeholder substitution
+ * @param options.role - Role to use for the message (defaults to User)
+ * @returns LlmInputMessage
+ */
+function formatOperateMessage(input, options) {
+    const content = options?.data ? placeholders(input, options.data) : input;
+    return {
+        content,
+        role: options?.role || LlmMessageRole.User,
+        type: LlmMessageType.Message,
+    };
+}
+
+/**
+ * Converts various input types to a standardized LlmHistory format
+ * @param input - String, LlmInputMessage, or LlmHistory to format
+ * @param options - Optional configuration
+ * @param options.data - Data to use for placeholder substitution
+ * @param options.role - Role to use when converting a string to LlmInputMessage (defaults to User)
+ * @returns Standardized LlmHistory array
+ */
+function formatOperateInput(input, options) {
+    // If input is already LlmHistory, return it
+    if (Array.isArray(input)) {
+        return input;
+    }
+    // If input is a string, convert it to LlmInputMessage
+    if (typeof input === "string") {
+        return [formatOperateMessage(input, options)];
+    }
+    // If input is LlmInputMessage, apply placeholders if data is provided
+    if (options?.data && typeof input.content === "string") {
+        return [
+            formatOperateMessage(input.content, {
+                data: options.data,
+                role: input.role || options?.role,
+            }),
+        ];
+    }
+    // Otherwise, just wrap the input in an array
+    return [input];
+}
+
+const getLogger$1 = () => log$1.lib({ lib: JAYPIE.LIB.LLM });
+const log = getLogger$1();
+
+// Turn policy constants
+const MAX_TURNS_ABSOLUTE_LIMIT = 72;
+const MAX_TURNS_DEFAULT_LIMIT = 12;
+/**
+ * Determines the maximum number of turns based on the provided options
+ *
+ * @param options - The LLM operate options
+ * @returns The maximum number of turns
+ */
+function maxTurnsFromOptions(options) {
+    // Default to single turn (1) when turns are disabled
+    // Handle the turns parameter
+    if (options.turns === undefined) {
+        // Default to default limit when undefined
+        return MAX_TURNS_DEFAULT_LIMIT;
+    }
+    else if (options.turns === true) {
+        // Explicitly set to true
+        return MAX_TURNS_DEFAULT_LIMIT;
+    }
+    else if (typeof options.turns === "number") {
+        if (options.turns > 0) {
+            // Positive number - use that limit (capped at absolute limit)
+            return Math.min(options.turns, MAX_TURNS_ABSOLUTE_LIMIT);
+        }
+        else if (options.turns < 0) {
+            // Negative number - use default limit
+            return MAX_TURNS_DEFAULT_LIMIT;
+        }
+        // If turns is 0, return 1 (disabled)
+        return 1;
+    }
+    // All other values (false, null, etc.) will return 1 (disabled)
+    return 1;
+}
+
 function naturalZodSchema(definition) {
     if (Array.isArray(definition)) {
         if (definition.length === 0) {
@@ -106,129 +271,190 @@ function naturalZodSchema(definition) {
     }
 }
 
-// Logger
-const getLogger = () => log.lib({ lib: JAYPIE.LIB.LLM });
-// Client initialization
-async function initializeClient({ apiKey, } = {}) {
-    const logger = getLogger();
-    const resolvedApiKey = apiKey || (await getEnvSecret("OPENAI_API_KEY"));
-    if (!resolvedApiKey) {
-        throw new ConfigurationError("The application could not resolve the requested keys");
+//
+// Constants
+//
+const DEFAULT_MIN = 0;
+const DEFAULT_MAX = 1;
+//
+// Helper Functions
+//
+/**
+ * Clamps a number between optional minimum and maximum values
+ * @param num - The number to clamp
+ * @param min - Optional minimum value
+ * @param max - Optional maximum value
+ * @returns The clamped number
+ */
+const clamp = (num, min, max) => {
+    let result = num;
+    if (typeof min === "number")
+        result = Math.max(result, min);
+    if (typeof max === "number")
+        result = Math.min(result, max);
+    return result;
+};
+/**
+ * Validates that min is not greater than max
+ * @param min - Optional minimum value
+ * @param max - Optional maximum value
+ * @throws {ConfigurationError} If min is greater than max
+ */
+const validateBounds = (min, max) => {
+    if (typeof min === "number" && typeof max === "number" && min > max) {
+        throw new ConfigurationError(`Invalid bounds: min (${min}) cannot be greater than max (${max})`);
     }
-    const client = new OpenAI({ apiKey: resolvedApiKey });
-    logger.trace("Initialized OpenAI client");
-    return client;
-}
-function formatSystemMessage(systemPrompt, { data, placeholders: placeholders$1 } = {}) {
-    const content = placeholders$1?.system === false
-        ? systemPrompt
-        : placeholders(systemPrompt, data);
-    return {
-        role: "developer",
-        content,
-    };
-}
-function formatUserMessage(message, { data, placeholders: placeholders$1 } = {}) {
-    const content = placeholders$1?.message === false
-        ? message
-        : placeholders(message, data);
-    return {
-        role: "user",
-        content,
+};
+//
+// Main
+//
+/**
+ * Creates a random number generator with optional seeding
+ *
+ * @param defaultSeed - Seed string for the default RNG
+ * @returns A function that generates random numbers based on provided options
+ *
+ * @example
+ * const rng = random("default-seed");
+ *
+ * // Generate a random float between 0 and 1
+ * const basic = rng();
+ *
+ * // Generate an integer between 1 and 10
+ * const integer = rng({ min: 1, max: 10, integer: true });
+ *
+ * // Generate from normal distribution
+ * const normal = rng({ mean: 50, stddev: 10 });
+ *
+ * // Use consistent seeding
+ * const seeded = rng({ seed: "my-seed" });
+ */
+function random$1(defaultSeed) {
+    // Initialize default seeded RNG
+    const defaultRng = RandomLib.clone(defaultSeed);
+    // Store per-seed RNGs
+    const seedMap = new Map();
+    const rngFn = ({ min, max: providedMax, mean, stddev, integer = false, start = 0, seed, precision, currency = false, } = {}) => {
+        // Select the appropriate RNG based on seed
+        const rng = seed
+            ? seedMap.get(seed) ||
+                (() => {
+                    const newRng = RandomLib.clone(seed);
+                    seedMap.set(seed, newRng);
+                    return newRng;
+                })()
+            : defaultRng;
+        // If only min is set, set max to min*2, but keep track of whether max was provided
+        let max = providedMax;
+        if (typeof min === "number" && typeof max !== "number") {
+            max = min * 2;
+        }
+        validateBounds(min, max);
+        // Determine effective precision based on parameters
+        const getEffectivePrecision = () => {
+            if (integer)
+                return 0;
+            const precisions = [];
+            if (typeof precision === "number" && precision >= 0) {
+                precisions.push(precision);
+            }
+            if (currency) {
+                precisions.push(2);
+            }
+            // Return the lowest precision if any are set, undefined otherwise
+            return precisions.length > 0 ? Math.min(...precisions) : undefined;
+        };
+        // Helper function to apply precision
+        const applyPrecision = (value) => {
+            const effectivePrecision = getEffectivePrecision();
+            if (typeof effectivePrecision === "number") {
+                const factor = Math.pow(10, effectivePrecision);
+                return Math.round(value * factor) / factor;
+            }
+            return value;
+        };
+        // Use normal distribution if both mean and stddev are provided
+        if (typeof mean === "number" && typeof stddev === "number") {
+            const normalDist = rng.normal(mean, stddev);
+            const value = normalDist();
+            // Only clamp if min/max are defined
+            const clampedValue = clamp(value, min, providedMax);
+            // Switch to uniform distribution only if both bounds were explicitly provided and exceeded
+            if (typeof min === "number" &&
+                typeof providedMax === "number" &&
+                clampedValue !== value) {
+                const baseValue = integer ? rng.int(min, max) : rng.float(min, max);
+                return applyPrecision(start + baseValue);
+            }
+            return applyPrecision(start + (integer ? Math.round(clampedValue) : clampedValue));
+        }
+        // For uniform distribution, use defaults if min/max are undefined
+        const uniformMin = typeof min === "number" ? min : DEFAULT_MIN;
+        const uniformMax = typeof max === "number" ? max : DEFAULT_MAX;
+        const baseValue = integer
+            ? rng.int(uniformMin, uniformMax)
+            : rng.float(uniformMin, uniformMax);
+        return applyPrecision(start + baseValue);
     };
+    return rngFn;
 }
-function prepareMessages(message, { system, data, placeholders } = {}) {
-    const logger = getLogger();
-    const messages = [];
-    if (system) {
-        const systemMessage = formatSystemMessage(system, { data, placeholders });
-        messages.push(systemMessage);
-        logger.trace(`System message: ${systemMessage.content?.length} characters`);
+
+/**
+ * Helper function to safely call a function that might throw
+ * @param fn Function to call safely
+ */
+function callSafely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // Silently catch any errors from the function
     }
-    const userMessage = formatUserMessage(message, { data, placeholders });
-    messages.push(userMessage);
-    logger.trace(`User message: ${userMessage.content?.length} characters`);
-    return messages;
-}
-// Completion requests
-async function createStructuredCompletion(client, { messages, responseSchema, model, }) {
-    const logger = getLogger();
-    logger.trace("Using structured output");
-    const zodSchema = responseSchema instanceof z.ZodType
-        ? responseSchema
-        : naturalZodSchema(responseSchema);
-    const completion = await client.beta.chat.completions.parse({
-        messages,
-        model,
-        response_format: zodResponseFormat(zodSchema, "response"),
-    });
-    logger.var({ assistantReply: completion.choices[0].message.parsed });
-    return completion.choices[0].message.parsed;
-}
-async function createTextCompletion(client, { messages, model, }) {
-    const logger = getLogger();
-    logger.trace("Using text output (unstructured)");
-    const completion = await client.chat.completions.create({
-        messages,
-        model,
-    });
-    logger.trace(`Assistant reply: ${completion.choices[0]?.message?.content?.length} characters`);
-    return completion.choices[0]?.message?.content || "";
 }
-
-const DEFAULT_TOOL_TYPE = "function";
-class Toolkit {
-    constructor(tools, options) {
-        this._tools = tools;
-        this._options = options || {};
-        this.explain = this._options.explain ? true : false;
+/**
+ * Attempts to parse a value as a number. Returns the original input if parsing fails or results in NaN.
+ * @param input - The value to attempt to parse as a number
+ * @param options - Optional configuration
+ * @param options.defaultValue - Default value to return if parsing fails or results in NaN
+ * @param options.warnFunction - Function to call with warning message if parsing fails or results in NaN
+ * @returns The parsed number, defaultValue (if specified and parsing fails), or the original input
+ */
+function tryParseNumber(input, options) {
+    if (input === null || input === undefined) {
+        return input;
     }
-    get tools() {
-        return this._tools.map((tool) => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const toolCopy = { ...tool };
-            delete toolCopy.call;
-            if (this.explain && toolCopy.parameters?.type === "object") {
-                if (toolCopy.parameters?.properties) {
-                    if (!toolCopy.parameters.properties.__Explanation) {
-                        toolCopy.parameters.properties.__Explanation = {
-                            type: "string",
-                            description: "Explain the reasoning behind this function call. What is the expected result? Describe possible next steps and the conditions under which they should be taken.",
-                        };
-                    }
-                }
+    try {
+        const parsed = Number(input);
+        if (Number.isNaN(parsed)) {
+            if (options?.warnFunction) {
+                const warningMessage = `Failed to parse "${String(input)}" as number`;
+                callSafely(() => options.warnFunction(warningMessage));
             }
-            // Set default type if not provided
-            if (!toolCopy.type) {
-                toolCopy.type = DEFAULT_TOOL_TYPE;
-            }
-            return toolCopy;
-        });
-    }
-    async call({ name, arguments: args }) {
-        const tool = this._tools.find((t) => t.name === name);
-        if (!tool) {
-            throw new Error(`Tool '${name}' not found`);
+            return typeof options?.defaultValue === "number"
+                ? options.defaultValue
+                : input;
         }
-        let parsedArgs;
-        try {
-            parsedArgs = JSON.parse(args);
-            if (this.explain) {
-                delete parsedArgs.__Explanation;
+        return parsed;
+    }
+    catch (error) {
+        if (options?.warnFunction) {
+            let errorMessage = "";
+            if (error instanceof Error) {
+                errorMessage = error.message;
             }
+            const warningMessage = `Error parsing "${String(input)}" as number${errorMessage ? "; " + errorMessage : ""}`;
+            callSafely(() => options.warnFunction(warningMessage));
         }
-        catch {
-            parsedArgs = args;
-        }
-        const result = tool.call(parsedArgs);
-        if (result instanceof Promise) {
-            return await result;
-        }
-        return result;
+        return typeof options?.defaultValue === "number"
+            ? options.defaultValue
+            : input;
     }
 }
 
+//
+//
 // Constants
+//
 const MAX_RETRIES_ABSOLUTE_LIMIT = 72;
 const MAX_RETRIES_DEFAULT_LIMIT = 6;
 // Retry policy constants
@@ -250,71 +476,163 @@ const NOT_RETRYABLE_ERRORS = [
     RateLimitError,
     UnprocessableEntityError,
 ];
-// Turn policy constants
-const MAX_TURNS_ABSOLUTE_LIMIT = 72;
-const MAX_TURNS_DEFAULT_LIMIT = 12;
-//
+const ERROR = {
+    BAD_FUNCTION_CALL: "Bad Function Call",
+};
 //
-// Helpers
 //
-function maxTurnsFromOptions(options) {
-    // Default to single turn (1) when turns are disabled
-    // Handle the turns parameter
-    if (options.turns === undefined) {
-        // Default to default limit when undefined
-        return MAX_TURNS_DEFAULT_LIMIT;
+// Helpers
+//
+/**
+ * Creates the request options for the OpenAI API call
+ *
+ * @param input - The formatted input messages
+ * @param options - The LLM operation options
+ * @returns The request options for the OpenAI API
+ */
+function createRequestOptions(input, options = {}) {
+    const requestOptions = {
+        model: options?.model || PROVIDER.OPENAI.MODEL.DEFAULT,
+        input,
+    };
+    // Add user if provided
+    if (options?.user) {
+        requestOptions.user = options.user;
     }
-    else if (options.turns === true) {
-        // Explicitly set to true
-        return MAX_TURNS_DEFAULT_LIMIT;
+    // Add any provider-specific options
+    if (options?.providerOptions) {
+        Object.assign(requestOptions, options.providerOptions);
     }
-    else if (typeof options.turns === "number") {
-        if (options.turns > 0) {
-            // Positive number - use that limit (capped at absolute limit)
-            return Math.min(options.turns, MAX_TURNS_ABSOLUTE_LIMIT);
+    // Handle instructions or system message
+    if (options?.instructions) {
+        // Apply placeholders to instructions if data is provided and placeholders.instructions is undefined or true
+        requestOptions.instructions =
+            options.data &&
+                (options.placeholders?.instructions === undefined ||
+                    options.placeholders?.instructions)
+                ? placeholders(options.instructions, options.data)
+                : options.instructions;
+    }
+    // Handle developer message as system message
+    // @ts-expect-error Testing invalid option
+    if (options?.developer) {
+        log.warn("Developer message provided but not supported. Using as system message.");
+        // @ts-expect-error Testing invalid option
+        requestOptions.system = options.developer;
+    }
+    // Handle structured output format
+    if (options?.format) {
+        // Check if format is a JsonObject with type "json_schema"
+        if (typeof options.format === "object" &&
+            options.format !== null &&
+            !Array.isArray(options.format) &&
+            options.format.type === "json_schema") {
+            // Direct pass-through for JsonObject with type "json_schema"
+            requestOptions.text = {
+                format: options.format,
+            };
         }
-        else if (options.turns < 0) {
-            // Negative number - use default limit
-            return MAX_TURNS_DEFAULT_LIMIT;
+        else {
+            // Convert NaturalSchema to Zod schema if needed
+            const zodSchema = options.format instanceof z.ZodType
+                ? options.format
+                : naturalZodSchema(options.format);
+            const responseFormat = zodResponseFormat(zodSchema, "response");
+            // Set up structured output format in the format expected by the test
+            requestOptions.text = {
+                format: {
+                    name: responseFormat.json_schema.name,
+                    schema: responseFormat.json_schema.schema,
+                    strict: responseFormat.json_schema.strict,
+                    type: responseFormat.type,
+                },
+            };
         }
-        // If turns is 0, return 1 (disabled)
-        return 1;
     }
-    // All other values (false, null, etc.) will return 1 (disabled)
-    return 1;
+    // Create toolkit and add tools if provided
+    if (options.tools?.length) {
+        const explain = options?.explain ?? false;
+        const toolkit = new Toolkit(options.tools, { explain });
+        requestOptions.tools = toolkit.tools;
+    }
+    return requestOptions;
 }
 //
 //
 // Main
 //
-async function operate(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-input, options = {}, context = {
+async function operate(input, options = {}, context = {
     client: new OpenAI(),
 }) {
-    const log = getLogger();
+    //
+    //
+    // Setup
+    //
     const openai = context.client;
-    // Validate
     if (!context.maxRetries) {
         context.maxRetries = MAX_RETRIES_DEFAULT_LIMIT;
     }
-    const model = options?.model || PROVIDER.OPENAI.MODEL.DEFAULT;
-    // Setup
     let retryCount = 0;
     let retryDelay = INITIAL_RETRY_DELAY_MS;
     const maxRetries = Math.min(context.maxRetries, MAX_RETRIES_ABSOLUTE_LIMIT);
-    const allResponses = [];
+    const returnResponse = {
+        history: [],
+        output: [],
+        responses: [],
+        status: LlmResponseStatus.InProgress,
+        usage: {
+            input: 0,
+            output: 0,
+            reasoning: 0,
+            total: 0,
+        },
+    };
+    // Convert string input to array format with placeholders if needed
+    let currentInput = formatOperateInput(input);
+    if (options?.data &&
+        (options.placeholders?.input === undefined || options.placeholders?.input)) {
+        currentInput = formatOperateInput(input, {
+            data: options?.data,
+        });
+    }
+    // If history is provided, merge it with currentInput
+    if (options.history) {
+        currentInput = [...options.history, ...currentInput];
+    }
+    // If system message is provided, add it to the beginning of the input
+    if (options?.system) {
+        const systemMessage = options.data && options.placeholders?.system !== false
+            ? placeholders(options.system, options.data)
+            : options.system;
+        // Create system message
+        const systemInputMessage = {
+            content: systemMessage,
+            role: LlmMessageRole.System,
+            type: LlmMessageType.Message,
+        };
+        // Check if history starts with an identical system message
+        const firstMessage = currentInput[0];
+        const isIdenticalSystemMessage = firstMessage?.type === LlmMessageType.Message &&
+            firstMessage?.role === LlmMessageRole.System &&
+            firstMessage?.content === systemMessage;
+        // Only prepend if not identical
+        if (!isIdenticalSystemMessage) {
+            // Remove any existing system message from the beginning
+            if (currentInput[0]?.type === LlmMessageType.Message &&
+                currentInput[0]?.role === LlmMessageRole.System) {
+                currentInput = currentInput.slice(1);
+            }
+            currentInput = [systemInputMessage, ...currentInput];
+        }
+    }
+    // Initialize history with currentInput
+    returnResponse.history = [...currentInput];
     // Determine max turns from options
     const maxTurns = maxTurnsFromOptions(options);
     const enableMultipleTurns = maxTurns > 1;
     let currentTurn = 0;
-    let currentInput = input;
-    let toolkit;
-    const explain = options?.explain ?? false;
-    // Initialize toolkit if tools are provided
-    if (options.tools?.length) {
-        toolkit = new Toolkit(options.tools, { explain });
-    }
+    // Build request options outside the retry loop
+    const requestOptions = createRequestOptions(currentInput, options);
     // OpenAI Multi-turn Loop
     while (currentTurn < maxTurns) {
         currentTurn++;
@@ -323,126 +641,88 @@ input, options = {}, context = {
         // OpenAI Retry Loop
         while (true) {
             try {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const requestOptions = {
-                    model,
-                    input: typeof currentInput === "string" &&
-                        options?.data &&
-                        (options.placeholders?.input === undefined ||
-                            options.placeholders?.input)
-                        ? placeholders(currentInput, options.data)
-                        : currentInput,
-                };
-                if (options?.user) {
-                    requestOptions.user = options.user;
-                }
-                // Add any provider-specific options
-                if (options?.providerOptions) {
-                    Object.assign(requestOptions, options.providerOptions);
-                }
-                if (options?.instructions) {
-                    // Apply placeholders to instructions if data is provided and placeholders.instructions is undefined or true
-                    requestOptions.instructions =
-                        options.data &&
-                            (options.placeholders?.instructions === undefined ||
-                                options.placeholders?.instructions)
-                            ? placeholders(options.instructions, options.data)
-                            : options.instructions;
-                }
-                else if (options?.system) {
-                    // Check for illegal system option, use it as instructions, and log a warning
-                    log.warn("[operate] Use 'instructions' instead of 'system'.");
-                    // Apply placeholders to system if data is provided and placeholders.instructions is undefined or true
-                    requestOptions.instructions =
-                        options.data &&
-                            (options.placeholders?.instructions === undefined ||
-                                options.placeholders?.instructions)
-                            ? placeholders(options.system, options.data)
-                            : options.system;
-                }
-                if (options?.format) {
-                    // Check if format is a JsonObject with type "json_schema"
-                    if (typeof options.format === "object" &&
-                        options.format !== null &&
-                        !Array.isArray(options.format) &&
-                        options.format.type === "json_schema") {
-                        // Direct pass-through for JsonObject with type "json_schema"
-                        requestOptions.text = {
-                            format: options.format,
-                        };
-                    }
-                    else {
-                        // Convert NaturalSchema to Zod schema if needed
-                        const zodSchema = options.format instanceof z.ZodType
-                            ? options.format
-                            : naturalZodSchema(options.format);
-                        const responseFormat = zodResponseFormat(zodSchema, "response");
-                        // Set up structured output format in the format expected by the test
-                        requestOptions.text = {
-                            format: {
-                                name: responseFormat.json_schema.name,
-                                schema: responseFormat.json_schema.schema,
-                                strict: responseFormat.json_schema.strict,
-                                type: responseFormat.type,
-                            },
-                        };
-                    }
-                }
-                // Add tools if toolkit is initialized
-                if (toolkit) {
-                    requestOptions.tools = toolkit.tools;
-                }
+                // Log appropriate message based on turn number
                 if (currentTurn > 1) {
                     log.trace(`[operate] Calling OpenAI Responses API - ${currentTurn}`);
                 }
                 else {
                     log.trace("[operate] Calling OpenAI Responses API");
                 }
-                log.var({ requestOptions });
                 // Use type assertion to handle the OpenAI SDK response type
-                const currentResponse = (await openai.responses.create(requestOptions));
+                const currentResponse = (await openai.responses.create(
+                // @ts-expect-error error claims missing non-required id, status
+                requestOptions));
                 if (retryCount > 0) {
                     log.debug(`OpenAI API call succeeded after ${retryCount} retries`);
                 }
-                // Add the entire response to allResponses
-                allResponses.push(currentResponse);
+                // Add the response to the responses array
+                returnResponse.responses.push(currentResponse);
+                // Accumulate token usage from the current response
+                if (currentResponse.usage) {
+                    returnResponse.usage.input += currentResponse.usage.input_tokens || 0;
+                    returnResponse.usage.output +=
+                        currentResponse.usage.output_tokens || 0;
+                    returnResponse.usage.total += currentResponse.usage.total_tokens || 0;
+                    if (currentResponse.usage.output_tokens_details?.reasoning_tokens) {
+                        returnResponse.usage.reasoning =
+                            (returnResponse.usage.reasoning || 0) +
+                                currentResponse.usage.output_tokens_details.reasoning_tokens;
+                    }
+                }
                 // Check if we need to process function calls for multi-turn conversations
                 let hasFunctionCall = false;
                 try {
                     if (currentResponse.output && Array.isArray(currentResponse.output)) {
                         // New OpenAI API format with output array
                         for (const output of currentResponse.output) {
-                            if (output.type === "function_call") {
+                            returnResponse.output.push(output);
+                            returnResponse.history.push(output);
+                            if (output.type === LlmMessageType.FunctionCall) {
                                 hasFunctionCall = true;
+                                let toolkit;
+                                const explain = options?.explain ?? false;
+                                // Initialize toolkit if tools are provided for multi-turn function calling
+                                if (options.tools?.length) {
+                                    toolkit = new Toolkit(options.tools, { explain });
+                                }
                                 if (toolkit && enableMultipleTurns) {
                                     try {
-                                        // Parse arguments for validation
-                                        JSON.parse(output.arguments);
                                         // Call the tool and ensure the result is resolved if it's a Promise
                                         log.trace(`[operate] Calling tool - ${output.name}`);
+                                        returnResponse.content = `${LlmMessageType.FunctionCall}:${output.name}${output.arguments}#${output.call_id}`;
                                         const result = await toolkit.call({
                                             name: output.name,
                                             arguments: output.arguments,
                                         });
-                                        // Prepare for next turn by adding function call and result
-                                        // Add the function call to the input for the next turn
-                                        if (typeof currentInput === "string") {
-                                            // Convert string input to array format for the first turn
-                                            currentInput = [{ content: currentInput, role: "user" }];
-                                        }
                                         // Add model's function call and result
                                         if (Array.isArray(currentInput)) {
                                             currentInput.push(output);
                                             // Add function call result
-                                            currentInput.push({
-                                                type: "function_call_output",
+                                            const functionCallOutput = {
                                                 call_id: output.call_id,
                                                 output: JSON.stringify(result),
-                                            });
+                                                type: LlmMessageType.FunctionCallOutput,
+                                            };
+                                            currentInput.push(functionCallOutput);
+                                            returnResponse.output.push(functionCallOutput);
+                                            returnResponse.history.push(functionCallOutput);
+                                            returnResponse.content = `${LlmMessageType.FunctionCallOutput}:${functionCallOutput.output}#${functionCallOutput.call_id}`;
                                         }
                                     }
                                     catch (error) {
-                                        log.error(`Error executing function call ${output.name}:`, error);
+                                        // TODO: but I do need to tell the model that something went wrong, right?
+                                        const jaypieError = new BadGatewayError();
+                                        const detail = [
+                                            `Error executing function call ${output.name}.`,
+                                            error.message,
+                                        ].join("\n");
+                                        returnResponse.error = {
+                                            detail,
+                                            status: jaypieError.status,
+                                            title: ERROR.BAD_FUNCTION_CALL,
+                                        };
+                                        log.error(`Error executing function call ${output.name}`);
+                                        log.var({ error });
                                         // We don't add error messages to allResponses here as we want to keep the original response objects
                                     }
                                 }
@@ -450,6 +730,12 @@ input, options = {}, context = {
                                     log.warn("Model requested function call but no toolkit available");
                                 }
                             }
+                            if (output.type === LlmMessageType.Message) {
+                                if (output.content?.[0] &&
+                                    output.content[0].type === LlmMessageType.OutputText) {
+                                    returnResponse.content = output.content[0].text;
+                                }
+                            }
                         }
                     }
                 }
@@ -461,12 +747,21 @@ input, options = {}, context = {
                 }
                 // If there's no function call or we can't take another turn, exit the loop
                 if (!hasFunctionCall || !enableMultipleTurns) {
-                    return allResponses;
+                    returnResponse.status = LlmResponseStatus.Completed;
+                    return returnResponse;
                 }
                 // If we've reached the maximum number of turns, exit the loop
                 if (currentTurn >= maxTurns) {
-                    log.warn(`Model requested function call but exceeded ${maxTurns} turns`);
-                    return allResponses;
+                    const error = new TooManyRequestsError();
+                    const detail = `Model requested function call but exceeded ${maxTurns} turns`;
+                    log.warn(detail);
+                    returnResponse.status = LlmResponseStatus.Incomplete;
+                    returnResponse.error = {
+                        detail,
+                        status: error.status,
+                        title: error.title,
+                    };
+                    return returnResponse;
                 }
                 // Continue to next turn
                 break;
@@ -513,13 +808,88 @@ input, options = {}, context = {
             }
         }
     }
-    // If we've reached the maximum number of turns, return all responses
-    return allResponses;
+    // * All possible paths should return a response; getting here is an error
+    // The main loop is `currentTurn < maxTurns` and `currentTurn >= maxTurns` within the loop returns
+    log.warn("This should never happen");
+    returnResponse.status = LlmResponseStatus.Incomplete;
+    // Always return the full LlmOperateResponse object for consistency
+    return returnResponse;
+}
+
+// Logger
+const getLogger = () => log$1.lib({ lib: JAYPIE.LIB.LLM });
+// Client initialization
+async function initializeClient({ apiKey, } = {}) {
+    const logger = getLogger();
+    const resolvedApiKey = apiKey || (await getEnvSecret("OPENAI_API_KEY"));
+    if (!resolvedApiKey) {
+        throw new ConfigurationError$1("The application could not resolve the requested keys");
+    }
+    const client = new OpenAI({ apiKey: resolvedApiKey });
+    logger.trace("Initialized OpenAI client");
+    return client;
+}
+function formatSystemMessage(systemPrompt, { data, placeholders: placeholders$1 } = {}) {
+    const content = placeholders$1?.system === false
+        ? systemPrompt
+        : placeholders(systemPrompt, data);
+    return {
+        role: "developer",
+        content,
+    };
+}
+function formatUserMessage(message, { data, placeholders: placeholders$1 } = {}) {
+    const content = placeholders$1?.message === false
+        ? message
+        : placeholders(message, data);
+    return {
+        role: "user",
+        content,
+    };
+}
+function prepareMessages(message, { system, data, placeholders } = {}) {
+    const logger = getLogger();
+    const messages = [];
+    if (system) {
+        const systemMessage = formatSystemMessage(system, { data, placeholders });
+        messages.push(systemMessage);
+        logger.trace(`System message: ${systemMessage.content?.length} characters`);
+    }
+    const userMessage = formatUserMessage(message, { data, placeholders });
+    messages.push(userMessage);
+    logger.trace(`User message: ${userMessage.content?.length} characters`);
+    return messages;
+}
+// Completion requests
+async function createStructuredCompletion(client, { messages, responseSchema, model, }) {
+    const logger = getLogger();
+    logger.trace("Using structured output");
+    const zodSchema = responseSchema instanceof z.ZodType
+        ? responseSchema
+        : naturalZodSchema(responseSchema);
+    const completion = await client.beta.chat.completions.parse({
+        messages,
+        model,
+        response_format: zodResponseFormat(zodSchema, "response"),
+    });
+    logger.var({ assistantReply: completion.choices[0].message.parsed });
+    return completion.choices[0].message.parsed;
+}
+async function createTextCompletion(client, { messages, model, }) {
+    const logger = getLogger();
+    logger.trace("Using text output (unstructured)");
+    const completion = await client.chat.completions.create({
+        messages,
+        model,
+    });
+    logger.trace(`Assistant reply: ${completion.choices[0]?.message?.content?.length} characters`);
+    return completion.choices[0]?.message?.content || "";
 }
 
 class OpenAiProvider {
     constructor(model = PROVIDER.OPENAI.MODEL.DEFAULT, { apiKey } = {}) {
         this.log = getLogger();
+        this.conversationHistory = [];
         this.model = model;
         this.apiKey = apiKey;
     }
@@ -549,7 +919,28 @@ class OpenAiProvider {
     async operate(input, options = {}) {
         const client = await this.getClient();
         options.model = options?.model || this.model;
-        return operate(input, options, { client });
+        // TODO: Create a merged history including both the tracked history and any explicitly provided history
+        // Call operate with the updated options
+        const response = await operate(input, options, { client });
+        // TODO: Update conversation history with the input and response
+        return response;
+    }
+    /**
+     * Updates the conversation history with the latest input and response
+     * @param input The formatted input messages
+     * @param response The response from the model
+     */
+    updateConversationHistory(input, response) {
+        // Add the input to history
+        this.conversationHistory.push(...input);
+        // Add the response to history if it exists and has content
+        if (response && response.length > 0) {
+            // Extract the last response item and add it to history
+            const lastResponse = response[response.length - 1];
+            if (lastResponse) {
+                this.conversationHistory.push(lastResponse);
+            }
+        }
     }
 }
 
@@ -604,134 +995,6 @@ class Llm {
     }
 }
 
-//
-// Constants
-//
-const DEFAULT_MIN = 0;
-const DEFAULT_MAX = 1;
-//
-// Helper Functions
-//
-/**
- * Clamps a number between optional minimum and maximum values
- * @param num - The number to clamp
- * @param min - Optional minimum value
- * @param max - Optional maximum value
- * @returns The clamped number
- */
-const clamp = (num, min, max) => {
-    let result = num;
-    if (typeof min === "number")
-        result = Math.max(result, min);
-    if (typeof max === "number")
-        result = Math.min(result, max);
-    return result;
-};
-/**
- * Validates that min is not greater than max
- * @param min - Optional minimum value
- * @param max - Optional maximum value
- * @throws {ConfigurationError} If min is greater than max
- */
-const validateBounds = (min, max) => {
-    if (typeof min === "number" && typeof max === "number" && min > max) {
-        throw new ConfigurationError$1(`Invalid bounds: min (${min}) cannot be greater than max (${max})`);
-    }
-};
-//
-// Main
-//
-/**
- * Creates a random number generator with optional seeding
- *
- * @param defaultSeed - Seed string for the default RNG
- * @returns A function that generates random numbers based on provided options
- *
- * @example
- * const rng = random("default-seed");
- *
- * // Generate a random float between 0 and 1
- * const basic = rng();
- *
- * // Generate an integer between 1 and 10
- * const integer = rng({ min: 1, max: 10, integer: true });
- *
- * // Generate from normal distribution
- * const normal = rng({ mean: 50, stddev: 10 });
- *
- * // Use consistent seeding
- * const seeded = rng({ seed: "my-seed" });
- */
-const random$1 = (defaultSeed) => {
-    // Initialize default seeded RNG
-    const defaultRng = RandomLib.clone(defaultSeed);
-    // Store per-seed RNGs
-    const seedMap = new Map();
-    const rngFn = ({ min, max: providedMax, mean, stddev, integer = false, start = 0, seed, precision, currency = false, } = {}) => {
-        // Select the appropriate RNG based on seed
-        const rng = seed
-            ? seedMap.get(seed) ||
-                (() => {
-                    const newRng = RandomLib.clone(seed);
-                    seedMap.set(seed, newRng);
-                    return newRng;
-                })()
-            : defaultRng;
-        // If only min is set, set max to min*2, but keep track of whether max was provided
-        let max = providedMax;
-        if (typeof min === "number" && typeof max !== "number") {
-            max = min * 2;
-        }
-        validateBounds(min, max);
-        // Determine effective precision based on parameters
-        const getEffectivePrecision = () => {
-            if (integer)
-                return 0;
-            const precisions = [];
-            if (typeof precision === "number" && precision >= 0) {
-                precisions.push(precision);
-            }
-            if (currency) {
-                precisions.push(2);
-            }
-            // Return the lowest precision if any are set, undefined otherwise
-            return precisions.length > 0 ? Math.min(...precisions) : undefined;
-        };
-        // Helper function to apply precision
-        const applyPrecision = (value) => {
-            const effectivePrecision = getEffectivePrecision();
-            if (typeof effectivePrecision === "number") {
-                const factor = Math.pow(10, effectivePrecision);
-                return Math.round(value * factor) / factor;
-            }
-            return value;
-        };
-        // Use normal distribution if both mean and stddev are provided
-        if (typeof mean === "number" && typeof stddev === "number") {
-            const normalDist = rng.normal(mean, stddev);
-            const value = normalDist();
-            // Only clamp if min/max are defined
-            const clampedValue = clamp(value, min, providedMax);
-            // Switch to uniform distribution only if both bounds were explicitly provided and exceeded
-            if (typeof min === "number" &&
-                typeof providedMax === "number" &&
-                clampedValue !== value) {
-                const baseValue = integer ? rng.int(min, max) : rng.float(min, max);
-                return applyPrecision(start + baseValue);
-            }
-            return applyPrecision(start + (integer ? Math.round(clampedValue) : clampedValue));
-        }
-        // For uniform distribution, use defaults if min/max are undefined
-        const uniformMin = typeof min === "number" ? min : DEFAULT_MIN;
-        const uniformMax = typeof max === "number" ? max : DEFAULT_MAX;
-        const baseValue = integer
-            ? rng.int(uniformMin, uniformMax)
-            : rng.float(uniformMin, uniformMax);
-        return applyPrecision(start + baseValue);
-    };
-    return rngFn;
-};
-
 const random = {
     description: "Generate a random number with optional distribution, precision, range, and seeding",
     name: "random",
@@ -798,12 +1061,20 @@ const roll = {
         required: ["number", "sides"],
     },
     type: "function",
-    call: ({ number = 1, sides = 6 }) => {
+    call: ({ number = 1, sides = 6 } = {}) => {
         const rng = random$1();
         const rolls = [];
         let total = 0;
-        for (let i = 0; i < number; i++) {
-            const rollValue = rng({ min: 1, max: sides, integer: true });
+        const parsedNumber = tryParseNumber(number, {
+            defaultValue: 1,
+            warnFunction: log.warn,
+        });
+        const parsedSides = tryParseNumber(sides, {
+            defaultValue: 6,
+            warnFunction: log.warn,
+        });
+        for (let i = 0; i < parsedNumber; i++) {
+            const rollValue = rng({ min: 1, max: parsedSides, integer: true });
             rolls.push(rollValue);
             total += rollValue;
         }
@@ -826,7 +1097,7 @@ const time = {
     },
     type: "function",
     call: ({ date } = {}) => {
-        if (date) {
+        if (typeof date === "number" || typeof date === "string") {
             const parsedDate = new Date(date);
             if (isNaN(parsedDate.getTime())) {
                 throw new Error(`Invalid date format: ${date}`);