@jaypie/llm 1.1.5 → 1.1.7

package/dist/index.js

@@ -1,8 +1,11 @@
-import { getEnvSecret } from '@jaypie/aws';
-import { log, JAYPIE, ConfigurationError, placeholders } from '@jaypie/core';
-import { OpenAI } from 'openai';
+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 RandomLib from 'random';
+import { getEnvSecret } from '@jaypie/aws';
+import { fetchWeatherApi } from 'openmeteo';
 
 const PROVIDER = {
     ANTHROPIC: {
@@ -18,7 +21,14 @@ const PROVIDER = {
         MODEL: {
             DEFAULT: "gpt-4o",
             GPT_4: "gpt-4",
+            GPT_4_O_MINI: "gpt-4o-mini",
             GPT_4_O: "gpt-4o",
+            GPT_4_5: "gpt-4.5-preview",
+            O1: "o1",
+            O1_MINI: "o1-mini",
+            O1_PRO: "o1-pro",
+            O3_MINI: "o3-mini",
+            O3_MINI_HIGH: "o3-mini-high",
         },
         NAME: "openai",
     },
@@ -34,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) {
@@ -96,73 +271,661 @@ function naturalZodSchema(definition) {
     }
 }
 
+//
+// 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})`);
+    }
+};
+//
+// 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;
+}
+
+/**
+ * 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
+    }
+}
+/**
+ * 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;
+    }
+    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));
+            }
+            return typeof options?.defaultValue === "number"
+                ? options.defaultValue
+                : input;
+        }
+        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));
+        }
+        return typeof options?.defaultValue === "number"
+            ? options.defaultValue
+            : input;
+    }
+}
+
+//
+//
+// Constants
+//
+const MAX_RETRIES_ABSOLUTE_LIMIT = 72;
+const MAX_RETRIES_DEFAULT_LIMIT = 6;
+// Retry policy constants
+const INITIAL_RETRY_DELAY_MS = 1000; // 1 second
+const MAX_RETRY_DELAY_MS = 32000; // 32 seconds
+const RETRY_BACKOFF_FACTOR = 2; // Exponential backoff multiplier
+const RETRYABLE_ERRORS = [
+    APIConnectionError,
+    APIConnectionTimeoutError,
+    InternalServerError,
+];
+const NOT_RETRYABLE_ERRORS = [
+    APIUserAbortError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+];
+const ERROR = {
+    BAD_FUNCTION_CALL: "Bad Function Call",
+};
+//
+//
+// 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;
+    }
+    // Add any provider-specific options
+    if (options?.providerOptions) {
+        Object.assign(requestOptions, options.providerOptions);
+    }
+    // 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;
+    }
+    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;
+    }
+    // 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 {
+            // 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,
+                },
+            };
+        }
+    }
+    // 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(input, options = {}, context = {
+    client: new OpenAI(),
+}) {
+    //
+    //
+    // Setup
+    //
+    const openai = context.client;
+    if (!context.maxRetries) {
+        context.maxRetries = MAX_RETRIES_DEFAULT_LIMIT;
+    }
+    let retryCount = 0;
+    let retryDelay = INITIAL_RETRY_DELAY_MS;
+    const maxRetries = Math.min(context.maxRetries, MAX_RETRIES_ABSOLUTE_LIMIT);
+    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,
+        });
+    }
+    // Determine max turns from options
+    const maxTurns = maxTurnsFromOptions(options);
+    const enableMultipleTurns = maxTurns > 1;
+    let currentTurn = 0;
+    // If history is provided, merge it with currentInput
+    if (options.history) {
+        currentInput = [...options.history, ...currentInput];
+    }
+    // Initialize history with currentInput
+    returnResponse.history = [...currentInput];
+    // Build request options outside the retry loop
+    const requestOptions = createRequestOptions(currentInput, options);
+    // OpenAI Multi-turn Loop
+    while (currentTurn < maxTurns) {
+        currentTurn++;
+        retryCount = 0;
+        retryDelay = INITIAL_RETRY_DELAY_MS;
+        // OpenAI Retry Loop
+        while (true) {
+            try {
+                // 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");
+                }
+                // Use type assertion to handle the OpenAI SDK response type
+                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 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) {
+                            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 {
+                                        // 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,
+                                        });
+                                        // Add model's function call and result
+                                        if (Array.isArray(currentInput)) {
+                                            currentInput.push(output);
+                                            // Add function call result
+                                            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) {
+                                        // 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
+                                    }
+                                }
+                                else if (!toolkit) {
+                                    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;
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    // If there's an error processing the response, log it but don't fail
+                    // This helps with test mocks that might not have the expected structure
+                    log.warn("Error processing response for function calls");
+                    log.var({ error });
+                }
+                // If there's no function call or we can't take another turn, exit the loop
+                if (!hasFunctionCall || !enableMultipleTurns) {
+                    returnResponse.status = LlmResponseStatus.Completed;
+                    return returnResponse;
+                }
+                // If we've reached the maximum number of turns, exit the loop
+                if (currentTurn >= maxTurns) {
+                    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;
+            }
+            catch (error) {
+                // Check if we've reached the maximum number of retries
+                if (retryCount >= maxRetries) {
+                    log.error(`OpenAI API call failed after ${maxRetries} retries`);
+                    log.var({ error });
+                    throw new BadGatewayError();
+                }
+                // Check if the error is not retryable
+                let isNotRetryable = false;
+                for (const notRetryableError of NOT_RETRYABLE_ERRORS) {
+                    if (error instanceof notRetryableError) {
+                        isNotRetryable = true;
+                        break;
+                    }
+                }
+                if (isNotRetryable) {
+                    log.error("OpenAI API call failed with non-retryable error");
+                    log.var({ error });
+                    throw new BadGatewayError();
+                }
+                // Warn if this error is not in our known retryable errors
+                let isUnknownError = true;
+                for (const retryableError of RETRYABLE_ERRORS) {
+                    if (error instanceof retryableError) {
+                        isUnknownError = false;
+                        break;
+                    }
+                }
+                if (isUnknownError) {
+                    log.warn("OpenAI API returned unknown error");
+                    log.var({ error });
+                }
+                // Log the error and retry
+                log.warn(`OpenAI API call failed. Retrying in ${retryDelay}ms...`);
+                // Wait before retrying
+                await sleep(retryDelay);
+                // Increase retry count and delay for next attempt (exponential backoff)
+                retryCount++;
+                retryDelay = Math.min(retryDelay * RETRY_BACKOFF_FACTOR, MAX_RETRY_DELAY_MS);
+            }
+        }
+    }
+    // * 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;
-        this.log = log.lib({ lib: JAYPIE.LIB.LLM });
     }
     async getClient() {
         if (this._client) {
             return this._client;
         }
-        const apiKey = this.apiKey || (await getEnvSecret("OPENAI_API_KEY"));
-        if (!apiKey) {
-            throw new ConfigurationError("The application could not resolve the requested keys");
-        }
-        this._client = new OpenAI({ apiKey });
-        this.log.trace("Initialized OpenAI client");
+        this._client = await initializeClient({ apiKey: this.apiKey });
         return this._client;
     }
     async send(message, options) {
         const client = await this.getClient();
-        const messages = [];
-        if (options?.system) {
-            const content = options?.placeholders?.system === false
-                ? options.system
-                : placeholders(options.system, options?.data);
-            const systemMessage = {
-                role: "developer",
-                content,
-            };
-            messages.push(systemMessage);
-            this.log.trace(`System message: ${content?.length} characters`);
-        }
-        const formattedMessage = options?.placeholders?.message === false
-            ? message
-            : placeholders(message, options?.data);
-        const userMessage = {
-            role: "user",
-            content: formattedMessage,
-        };
-        messages.push(userMessage);
-        this.log.trace(`User message: ${formattedMessage?.length} characters`);
+        const messages = prepareMessages(message, options || {});
+        const modelToUse = options?.model || this.model;
         if (options?.response) {
-            this.log.trace("Using structured output");
-            const zodSchema = options.response instanceof z.ZodType
-                ? options.response
-                : naturalZodSchema(options.response);
-            const completion = await client.beta.chat.completions.parse({
+            return createStructuredCompletion(client, {
                 messages,
-                model: options?.model || this.model,
-                response_format: zodResponseFormat(zodSchema, "response"),
+                responseSchema: options.response,
+                model: modelToUse,
             });
-            this.log.var({ assistantReply: completion.choices[0].message.parsed });
-            return completion.choices[0].message.parsed;
         }
-        this.log.trace("Using text output (unstructured)");
-        const completion = await client.chat.completions.create({
+        return createTextCompletion(client, {
             messages,
-            model: options?.model || this.model,
+            model: modelToUse,
         });
-        this.log.trace(`Assistant reply: ${completion.choices[0]?.message?.content?.length} characters`);
-        return completion.choices[0]?.message?.content || "";
+    }
+    async operate(input, options = {}) {
+        const client = await this.getClient();
+        options.model = options?.model || this.model;
+        // 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);
+            }
+        }
     }
 }
 
 class AnthropicProvider {
-    constructor(model = PROVIDER.ANTHROPIC.MODEL.DEFAULT) {
+    constructor(model = PROVIDER.ANTHROPIC.MODEL.DEFAULT, { apiKey } = {}) {
         this.model = model;
+        this.apiKey = apiKey;
     }
     async send(message) {
         // TODO: Implement Anthropic API call
@@ -171,16 +934,20 @@ class AnthropicProvider {
 }
 
 class Llm {
-    constructor(providerName = DEFAULT.PROVIDER.NAME) {
+    constructor(providerName = DEFAULT.PROVIDER.NAME, options = {}) {
         this._provider = providerName;
-        this._llm = this.createProvider(providerName);
+        this._options = options;
+        this._llm = this.createProvider(providerName, options);
     }
-    createProvider(providerName) {
+    createProvider(providerName, options = {}) {
+        const { apiKey, model } = options;
         switch (providerName) {
             case PROVIDER.OPENAI.NAME:
-                return new OpenAiProvider();
+                return new OpenAiProvider(model || PROVIDER.OPENAI.MODEL.DEFAULT, {
+                    apiKey,
+                });
             case PROVIDER.ANTHROPIC.NAME:
-                return new AnthropicProvider();
+                return new AnthropicProvider(model || PROVIDER.ANTHROPIC.MODEL.DEFAULT, { apiKey });
             default:
                 throw new Error(`Unsupported provider: ${providerName}`);
         }
@@ -188,12 +955,254 @@ class Llm {
     async send(message, options) {
         return this._llm.send(message, options);
     }
+    async operate(message, options = {}) {
+        if (!this._llm.operate) {
+            throw new NotImplementedError(`Provider ${this._provider} does not support operate method`);
+        }
+        return this._llm.operate(message, options);
+    }
     static async send(message, options) {
-        const { llm, ...messageOptions } = options || {};
-        const instance = new Llm(llm);
+        const { llm, apiKey, model, ...messageOptions } = options || {};
+        const instance = new Llm(llm, { apiKey, model });
         return instance.send(message, messageOptions);
     }
+    static async operate(message, options) {
+        const { llm, apiKey, model, ...operateOptions } = options || {};
+        const instance = new Llm(llm, { apiKey, model });
+        return instance.operate(message, operateOptions);
+    }
 }
 
-export { constants as LLM, Llm };
+const random = {
+    description: "Generate a random number with optional distribution, precision, range, and seeding",
+    name: "random",
+    parameters: {
+        type: "object",
+        properties: {
+            min: {
+                type: "number",
+                description: "Minimum value (inclusive). Default: 0. When used with mean/stddev, acts as a clamp on the normal distribution",
+            },
+            max: {
+                type: "number",
+                description: "Maximum value (inclusive). Default: 1. When used with mean/stddev, acts as a clamp on the normal distribution",
+            },
+            mean: {
+                type: "number",
+                description: "Mean value for normal distribution. When set with stddev, uses normal distribution (clamped by min/max if provided)",
+            },
+            stddev: {
+                type: "number",
+                description: "Standard deviation for normal distribution. When set with mean, uses normal distribution (clamped by min/max if provided)",
+            },
+            integer: {
+                type: "boolean",
+                description: "Whether to return an integer value. Default: false",
+            },
+            seed: {
+                type: "string",
+                description: "Seed string for consistent random generation. Default: undefined (uses default RNG)",
+            },
+            precision: {
+                type: "number",
+                description: "Number of decimal places for the result. Default: undefined (full precision)",
+            },
+            currency: {
+                type: "boolean",
+                description: "Whether to format as currency (2 decimal places). Default: false",
+            },
+        },
+        required: [],
+    },
+    type: "function",
+    call: (options) => {
+        const rng = random$1();
+        return rng(options);
+    },
+};
+
+const roll = {
+    description: "Roll one or more dice with a specified number of sides",
+    name: "roll",
+    parameters: {
+        type: "object",
+        properties: {
+            number: {
+                type: "number",
+                description: "Number of dice to roll. Default: 1",
+            },
+            sides: {
+                type: "number",
+                description: "Number of sides on each die. Default: 6",
+            },
+        },
+        required: ["number", "sides"],
+    },
+    type: "function",
+    call: ({ number = 1, sides = 6 } = {}) => {
+        const rng = random$1();
+        const rolls = [];
+        let total = 0;
+        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;
+        }
+        return { rolls, total };
+    },
+};
+
+const time = {
+    description: "Returns the provided date as an ISO UTC string or the current time if no date provided.",
+    name: "time",
+    parameters: {
+        type: "object",
+        properties: {
+            date: {
+                type: "string",
+                description: "Date string to convert to ISO UTC format. Default: current time",
+            },
+        },
+        required: [],
+    },
+    type: "function",
+    call: ({ date } = {}) => {
+        if (typeof date === "number" || typeof date === "string") {
+            const parsedDate = new Date(date);
+            if (isNaN(parsedDate.getTime())) {
+                throw new Error(`Invalid date format: ${date}`);
+            }
+            return parsedDate.toISOString();
+        }
+        return new Date().toISOString();
+    },
+};
+
+const weather = {
+    description: "Get current weather and forecast data for a specific location",
+    name: "weather",
+    parameters: {
+        type: "object",
+        properties: {
+            latitude: {
+                type: "number",
+                description: "Latitude of the location. Default: 42.051554533384866 (Evanston, IL)",
+            },
+            longitude: {
+                type: "number",
+                description: "Longitude of the location. Default: -87.6759911441785 (Evanston, IL)",
+            },
+            timezone: {
+                type: "string",
+                description: "Timezone for the location. Default: America/Chicago",
+            },
+            past_days: {
+                type: "number",
+                description: "Number of past days to include in the forecast. Default: 1",
+            },
+            forecast_days: {
+                type: "number",
+                description: "Number of forecast days to include. Default: 1",
+            },
+        },
+        required: [],
+    },
+    type: "function",
+    call: async ({ latitude = 42.051554533384866, longitude = -87.6759911441785, timezone = "America/Chicago", past_days = 1, forecast_days = 1, } = {}) => {
+        try {
+            const params = {
+                latitude,
+                longitude,
+                hourly: [
+                    "temperature_2m",
+                    "precipitation_probability",
+                    "precipitation",
+                ],
+                current: [
+                    "temperature_2m",
+                    "is_day",
+                    "showers",
+                    "cloud_cover",
+                    "wind_speed_10m",
+                    "relative_humidity_2m",
+                    "precipitation",
+                    "snowfall",
+                    "rain",
+                    "apparent_temperature",
+                ],
+                timezone,
+                past_days,
+                forecast_days,
+                wind_speed_unit: "mph",
+                temperature_unit: "fahrenheit",
+                precipitation_unit: "inch",
+            };
+            const url = "https://api.open-meteo.com/v1/forecast";
+            const responses = await fetchWeatherApi(url, params);
+            // Helper function to form time ranges
+            const range = (start, stop, step) => Array.from({ length: (stop - start) / step }, (_, i) => start + i * step);
+            // Process first location
+            const response = responses[0];
+            // Attributes for timezone and location
+            const utcOffsetSeconds = response.utcOffsetSeconds();
+            const timezoneAbbreviation = response.timezoneAbbreviation();
+            const current = response.current();
+            const hourly = response.hourly();
+            // Create weather data object
+            const weatherData = {
+                location: {
+                    latitude: response.latitude(),
+                    longitude: response.longitude(),
+                    timezone: response.timezone(),
+                    timezoneAbbreviation,
+                    utcOffsetSeconds,
+                },
+                current: {
+                    time: new Date((Number(current.time()) + utcOffsetSeconds) * 1000).toISOString(),
+                    temperature2m: current.variables(0).value(),
+                    isDay: current.variables(1).value(),
+                    showers: current.variables(2).value(),
+                    cloudCover: current.variables(3).value(),
+                    windSpeed10m: current.variables(4).value(),
+                    relativeHumidity2m: current.variables(5).value(),
+                    precipitation: current.variables(6).value(),
+                    snowfall: current.variables(7).value(),
+                    rain: current.variables(8).value(),
+                    apparentTemperature: current.variables(9).value(),
+                },
+                hourly: {
+                    time: range(Number(hourly.time()), Number(hourly.timeEnd()), hourly.interval()).map((t) => new Date((t + utcOffsetSeconds) * 1000).toISOString()),
+                    temperature2m: Array.from(hourly.variables(0).valuesArray()),
+                    precipitationProbability: Array.from(hourly.variables(1).valuesArray()),
+                    precipitation: Array.from(hourly.variables(2).valuesArray()),
+                },
+            };
+            return weatherData;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Weather API error: ${error.message}`);
+            }
+            throw new Error("Unknown error occurred while fetching weather data");
+        }
+    },
+};
+
+const toolkit = {
+    random,
+    roll,
+    time,
+    weather,
+};
+const tools = Object.values(toolkit);
+
+export { constants as LLM, Llm, toolkit, tools };
 //# sourceMappingURL=index.js.map