llaminate 0.1.0

package/src/llaminate.ts

@@ -0,0 +1,1326 @@
+/**
+ * @projectname Llaminate
+ * @author Oliver Moran <oliver.moran@gmail.com>
+ * @license
+ * Copyright 2026 Oliver Moran <oliver.moran@gmail.com>
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file at https://github.com/oliver-moran/llaminate
+ */
+
+/// <reference path="./llaminate.d.ts" />
+
+// To allow consumers to import the types from the main entry point
+export type {
+    LlaminateConfig,
+    LlaminateResponse,
+    LlaminateMessage } from "./llaminate.types.js";
+
+/* @ignore */
+const os = require("os");
+import Ajv from "ajv";
+import { Buffer } from "buffer";
+
+// @ts-ignore This will be replaced with a minified version in the buildprocess
+import { RateLimiter } from "./ratelimiter.min.js";
+
+const ajv = new Ajv();
+const validate = {
+    config: ajv.compile(require("./config.schema.json"))
+};
+
+// Polyfill for environments that don't support structuredClone (like Node.js
+// versions prior to 17 or some older browsers)
+const structuredClone = globalThis.structuredClone || ((obj) => JSON.parse(JSON.stringify(obj)));
+const noop = () => {};
+
+// read the file system.hbs and compile it into a function that takes a schema
+// and returns the system prompt string with the schema injected
+const SYSTEM_HBS = (() => {
+    const fs = require("fs");
+    const Handlebars = require("handlebars");
+    const template = Handlebars.compile(fs.readFileSync(require.resolve("./system.hbs"), "utf-8"));
+    return (schema) => template({ schema });
+})();
+
+// Dynamically determine the Llaminate version and Node.js version
+const { version: LLAMINATE_VERSION } = require("./build-info.json");
+const NODE_TITLE = process.title || "Node.js";
+const NODE_VERSION = process.version;
+const OS_TYPE = os.type();
+const OS_ARCH = os.arch();
+const USER_AGENT = `Llaminate/${LLAMINATE_VERSION} (https://github.com/oliver-moran/llaminate; ${NODE_TITLE}/${NODE_VERSION}; ${OS_TYPE}/${OS_ARCH})`;
+
+// Define the possible roles for messages in the conversation, which can be used
+// to indicate the source or purpose of each message. These roles can help the
+// LLM service understand the context of the conversation and respond
+// appropriately. The roles include "assistant" for messages generated by the
+// LLM, "developer" for messages from the developer or system, "system" for
+// system-level messages, "user" for messages from the user, and "tool" for
+// messages related to tool calls or responses.
+const enum ROLE {
+    ASSISTANT = "assistant",
+    DEVELOPER = "developer",
+    SYSTEM = "system",
+    USER = "user",
+    TOOL = "tool",
+}
+
+const ROLES = [
+    ROLE.ASSISTANT,
+    ROLE.DEVELOPER,
+    ROLE.SYSTEM,
+    ROLE.USER,
+    ROLE.TOOL
+];
+
+/**
+ * @classdesc Represents the Llaminate service for managing and interacting with AI models.
+ */
+export class Llaminate {
+
+    // PUBLIC STATIC PROPERTIES
+
+    /**
+     * @property {string} Llaminate.GIF MIME type for GIF images (`image/gif`).
+     * @property {string} Llaminate.JPEG MIME type for JPEG images (`image/jpeg`).
+     * @property {string} Llaminate.PDF MIME type for PDF files (`application/pdf`).
+     * @property {string} Llaminate.PNG MIME type for PNG images (`image/png`).
+     * @property {string} Llaminate.WEBP MIME type for WEBP images (`image/webp`).
+     * @description Static MIME types for various file formats.
+     * @module MimeTypes
+     * @memberof Llaminate
+     * @example
+     * const response = await mistral.complete("Summarize the content of this image.", {
+     *  attachments: [ { type: Llaminate.JPEG, url: "https://example.com/image.jpg" } ]
+     * });
+     */
+    public static readonly PDF = "application/pdf";
+    public static readonly JPEG = "image/jpeg";
+    public static readonly PNG = "image/png";
+    public static readonly GIF = "image/gif";
+    public static readonly WEBP = "image/webp";
+
+    /**
+     * @property {string} Llaminate.USER_AGENT The User-Agent string used in API
+     * requests.
+     * @property {string} Llaminate.VERSION The version of the Llaminate library.
+     * @description Static property for the Llaminate library version.
+     * @module Llaminate
+     * @memberof Llaminate
+     */
+    public static readonly VERSION = LLAMINATE_VERSION;
+    public static readonly USER_AGENT = USER_AGENT;
+
+    /**
+     * @property {string} Llaminate.ANTHROPIC Anthropic completions API endpoint.
+     * @property {string} Llaminate.DEEPSEEK Deepseek completions API endpoint.
+     * @property {string} Llaminate.GOOGLE Google completions API endpoint.
+     * @property {string} Llaminate.MISTRAL Mistral completions API endpoint.
+     * @property {string} Llaminate.OPENAI OpenAI completions API endpoint.
+     * @description Static properties for common LLM service endpoints, which
+     * can be used in the Llaminate configuration.
+     * @module Endpoints
+     * @memberof Llaminate
+     * @example
+     * const mistral = new Llaminate({
+     *   endpoint: Llaminate.MISTRAL,
+     *   key: "12345-abcde-67890-fghij-klm",
+     *   model: "mistral-small-latest"
+     * });
+     */
+    public static readonly MISTRAL = "https://api.mistral.ai/v1/chat/completions";
+    public static readonly OPENAI = "https://api.openai.com/v1/chat/completions";
+    public static readonly ANTHROPIC = "https://api.anthropic.com/v1/messages";
+    public static readonly GOOGLE = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions";
+    public static readonly DEEPSEEK = "https://api.deepseek.com/chat/completions";
+
+    // PRIVATE PROPERTIES
+
+    // The history of messages exchanged with the service.
+    private history: LlaminateMessage[] = [];
+
+    // The rate limiter instance for managing API request rates.
+    private readonly limiter: RateLimiter;
+
+    // The configuration options for the Llaminate service.
+    private readonly config: LlaminateConfig = {
+        endpoint: null,
+        key: null,
+        model: null,
+        tools: [],
+        system: [],
+        attachments: [],
+        window: 12,
+        headers: {},
+        options: {
+            parallel_tool_calls: true,
+            response_format: { type: "text" }
+        },
+        handler: async (name: string, args: Record<string, any>): Promise<any> => {
+            throw new Error(`No \`handler\` method provided for \`${name}\` was provided in the Llaminate configuration.`)
+        },
+        fetch: globalThis.fetch.bind(globalThis),
+        rpm: Infinity,
+    };
+
+    // CONSTRUCTOR
+
+    /**
+     * Constructs a new instance of the Llaminate class.
+     * @param {LlaminateConfig} config The configuration options for the
+     * Llaminate instance.
+     * @throws Will throw an error if the provided configuration is invalid.
+     * @example
+     * const mistral = new Llaminate({
+     *   endpoint: Llaminate.MISTRAL,
+     *   key: "12345-abcde-67890-fghij-klm",
+     *   model: "mistral-small-latest",
+     *   system: ["You are a sarcastic assistant who answers very briefly and bluntly."]
+     *   rpm: 720
+     * });
+     */
+    constructor(config: LlaminateConfig) {
+        validateConfig(config);
+
+        this.config.endpoint = config.endpoint;
+        this.config.key = config.key;
+        this.config.model = config.model;
+
+        this.config.schema = config.schema;
+
+        this.history = this.config.history || this.history;
+        // once the history is set from the config, we delete it to prevent it
+        // it being accidentially duplicated or merged with the internal
+        // history in future calls to complete or stream.
+        delete config.history;
+
+        this.config.tools = config.tools || this.config.tools;
+        this.config.system = config.system || this.config.system;
+        this.config.window = config.window || this.config.window;
+        this.config.headers = config.headers || this.config.headers;
+        this.config.options = {
+            ...this.config.options,
+            ...config.options,
+        };
+        this.config.handler = config.handler || this.config.handler;
+        this.config.fetch = config.fetch || this.config.fetch;
+
+        const quirks = getQuirks(this.config);
+        this.config.quirks = { ...quirks, ...config.quirks };
+
+        // Attachments are not allowed in the constructor
+        delete this.config.attachments;
+
+        deepFreeze(this.config);
+
+        this.limiter = new RateLimiter(config.rpm);
+    }
+
+    // PUBLIC METHODS
+
+    /**
+     * Sends a prompt to the LLM service and returns a chat completion response.
+     * @param { string | LlaminateMessage[] } prompt The input prompt or
+     * messages to send to the service.
+     * @param { LlaminateConfig } [config] Optional configuration settings for
+     * this completion.
+     * @returns { Promise<LlaminateResponse> } A promise resolving to a
+     * LlaminateResponse from the service.
+     * @throws Will throw an error if the prompt is invalid, the response is
+     * unsuccessful, or if the response does not conform to the expected format.
+     * @example
+     * // EXAMPLE 1: Simple prompt with default configuration
+     * const response = await mistral.complete("What's the capital of France?");
+     * console.log(response.message); // "Paris"
+     * @example
+     * // EXAMPLE 2: System messages set through configuration
+     * const response = await mistral.complete("What's the capital of France?", 
+     *   { system: [
+     *     "You are a children's geography tutor.",
+     *     "Always reply as if you are explaining to a child."
+     *   ] } );
+     * @example
+     * // EXAMPLE 3: An image attachment (supported depends on LLM model)
+     * const response = await mistral.complete(
+     *   "Generate a helpful HTML `alt` tag for this image.", {
+     *   attachments: [ { type: Llaminate.JPEG, url: "https://example.com/image.jpg" } ]
+     * });
+     * @example
+     * // EXAMPLE 4: Prompt with a pre-rolled conversation history
+     * const history = [
+     *   { role: "user", content: "What's a good name for a houseplant?" },
+     *   { role: "assistant", content: "How about Fernie Sanders?" },
+     *   { role: "user", content: "Nice. Any other suggestions?" },
+     *   { role: "assistant", content: "How about Leaf Erickson?" }
+     * ];
+     * const prompt = "Great. What could be its nickname?";
+     * const response = await mistral.complete(prompt, { history });
+     * @example
+     * // EXAMPLE 5: Rolling the conversation history into the prompt
+     * const messages = history.concat({ role: "user", content: prompt });
+     * const response = await mistral.complete(messages);
+     */
+    async complete(prompt: string | LlaminateMessage[], config?: LlaminateConfig): Promise<LlaminateResponse> {
+        const _config = generateCompletionConfig.call(this, config, false);
+        const messages = prepareMessageWindow.call(this, prompt, _config);
+        const result: LlaminateMessage[] = [];
+        const subtotal: Tokens = { input: 0, output: 0, total: 0 };
+
+        return await _complete.call(this, messages);
+
+        async function _complete(): Promise<LlaminateResponse> {
+            const response = await this.limiter.queue(
+                () => sendMessages([...messages, ...result], _config) );
+            if (!response.ok)
+                throw new Error(`HTTP status ${response.status} from ${_config.endpoint}.\n\n${await response.text()}`);
+
+            const completion = await response.json();
+            const message = completion?.choices?.[0]?.message || completion?.content?.[0] || null;
+
+            const tokens = getUsageFromCompletion(completion);
+            subtotal.input += tokens.input || 0;
+            subtotal.output += tokens.output || 0;
+            subtotal.total += tokens.total || subtotal.input + subtotal.output || 0;
+
+            const calls = message.tool_calls || transformAnthropicToolCalls(completion?.content) || [];
+            const role = message.role;
+
+            const recursed = await handleTools.call(this, role, calls, {
+                messages, result, subtotal, config: _config, recurse: _complete
+            });
+            if (recursed) return recursed;
+            else {
+                const content = validateResponse(
+                    message?.content || message?.text || "", _config
+                );
+                result.push({
+                    role: role || ROLE.ASSISTANT,
+                    content: content
+                });
+                updateHistory.call(this, prompt, result);
+                return generateOutputObject(content, result, subtotal, uuid_v4(), _config);
+            }
+        }
+	}
+
+    /**
+     * Sends a prompt to the LLM service and streams the response.
+     * @param { string | LlaminateMessage[] } prompt The input prompt or
+     * messages to send to the service.
+     * @param { LlaminateConfig } [config] Optional configuration settings for
+     * this completion.
+     * @yields { LlaminateResponse } An asynchronous generator yielding
+     * responses from the service.
+     * @throws Will throw an error if the prompt is invalid, the response is
+     * unsuccessful, or if the response does not conform to the expected format.
+     * @example
+     * // EXAMPLE 1: Streaming the response to a simple prompt
+     * const stream = mistral.stream("Tell me a joke and explain it.");
+     * for await (const response of stream) {
+     *   console.log(response.message);
+     * }
+     * @example
+     * // EXAMPLE 2: Streaming a response with a structured output
+     * const stream = mistral.stream("Tell me a joke and explain it.", {
+     *   schema: {
+     *     type: "object",
+     *     properties: {
+     *       joke: {
+     *         type: "string",
+     *         description: "Your response to the user's query."
+     *       },
+     *       explanation: {
+     *         type: "string",
+     *         description: "Your internal thoughts about the user's query."
+     *       },
+     *     },
+     *     required: ["joke", "explanation"],
+     *     additionalProperties: false,
+     *   }
+     * });
+     * for await (const response of stream) {
+     *   // Initially streams as a string until the JSON schema can be validated
+     *   console.log(response.message);
+     *   console.log(response.message?.joke);
+     *   console.log(response.message?.explanation);
+     * }
+     */
+    async *stream(prompt: string | LlaminateMessage[], config?: LlaminateConfig): AsyncGenerator<LlaminateResponse> {
+        const _config = generateCompletionConfig.call(this, config, true);
+        const messages = prepareMessageWindow.call(this, prompt, _config);
+        const result: LlaminateMessage[] = [];
+        const subtotal: Tokens = { input: 0, output: 0, total: 0 };
+
+        const stream = await _stream.call(this, messages);
+        for await (const result of stream) yield result;
+
+        async function* _stream(): AsyncGenerator<LlaminateResponse> {
+            const response = await this.limiter.queue(() => sendMessages(
+                [...messages, ...result], _config)
+            );
+
+            if (!response.ok)
+                throw new Error(`HTTP status ${response.status} from ${_config.endpoint}.\n\n${await response.text()}`);
+            if (!response.body)
+                throw new Error(`No readable stream from ${_config.endpoint}.\n\n${await response.text()}`);
+
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder('utf-8');
+
+            let buffer = "";
+            let content = "";
+            let role = "" as any;
+            let tokens: Tokens = { input: 0, output: 0, total: 0 };
+            let tools = [];
+
+            const uuid = uuid_v4();
+
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+
+                // Process each line in the buffer
+                let lines = buffer.split('\n');
+                // Keep the last incomplete line in the buffer
+                buffer = lines.pop()!;
+
+                for (const line of lines) {
+                    if (line.startsWith("data: ")) {
+
+                        try {
+                            // Extract data after "data: " and parse it as JSON
+                            const json = line.slice(6).trim();
+                            const completion = JSON.parse(json);
+                            const delta = completion.choices?.[0]?.delta || completion.delta;
+
+                            // Append the new content to the message
+                            content += delta?.content || delta?.text || "";
+                            // Update role, unless it is already complete
+                            if (!ROLES.includes(role)) role += delta?.role || "";
+                            // Merge tool calls (some LLM send these as deltas)
+                            tools = mergeToolsDeltas(tools, delta?.tool_calls || transformAnthropicToolCalls(completion.content_block)); // Merge any new tool calls with the existing ones
+
+                            const usage = getUsageFromCompletion(completion);
+                            tokens.input = usage.input || tokens.input;
+                            tokens.output = usage.output || tokens.output;
+                            tokens.total = usage.total || tokens.total;
+
+                            yield generateOutputObject(content, null, null, uuid);
+                        } catch (error) { /* meh */ }
+                    }
+                }
+            }
+
+            subtotal.input += tokens.input || 0;
+            subtotal.output += tokens.output || 0;
+            subtotal.total += tokens.total || subtotal.input + subtotal.output || 0;
+
+            const recursed = await handleTools.call(this, role, tools, {
+                messages, result, subtotal, config: _config, recurse: _stream
+            });
+            if (recursed) for await (const result of recursed) yield result;
+            else {
+                content = validateResponse(content, _config);
+                result.push({
+                    role: role || ROLE.ASSISTANT,
+                    content: content
+                });
+                updateHistory.call(this, prompt, result);
+                yield generateOutputObject(content, result, subtotal, uuid, _config);
+            }
+        }
+	}
+
+    /**
+     * Resets the chat history. This does not affect the configuration or any
+     * other settings.
+     * @returns void
+     * @example
+     * // EXAMPLE: Populating and then clearing the history
+     * mistral.complete("What's your name?"); // "John"
+     * mistral.complete("How do you spell that?"); // "J-O-H-N"
+     * mistral.clear();
+     * mistral.complete("Tell me again?"); // "Tell you what again?"
+     */
+    clear():void {
+        this.history = [];
+    }
+
+    /**
+     * Exports the chat history. By default, this exports the entire chat
+     * history. If a window is specified, only the most recent messages are
+     * returned. The window counts back each of the most recent user message, it
+     * includes assistant responses to these, and any system prompts set in the
+     * global configuration.
+     * @param { number } [window] The length of the window to retrieve.
+     * @returns { LlaminateMessage[] } An array of chat history messages.
+     * @example
+     * // EXAMPLE 1: Exporting the entire history of messages
+     * const history = mistral.export();
+     * localStorage.setItem('mistral-history', JSON.stringify(history));
+     * @example
+     * // EXAMPLE 2: Getting a window of recent messages
+     * // Returns the last 5 user-assistant interactions and all system prompts
+     * const history = mistral.export(5);
+     * console.log(history.length);
+     * // e.g. 14 = 5 user messages + 5 assistant replies (one that included a
+     * // tool call) + 2 system prompts
+     */
+    export(window: number = Infinity): LlaminateMessage[] {
+        // in the event of an invalid window value being passed (e.g. negative,
+        // zero, or NaN), set to 1 to return something rather than nothing
+        if (window && (isNaN(window) || window < 1)) window = 1;
+
+        const config = { ...this.config, window } as LlaminateConfig;
+        const history = getWindowFromHistory(this.history, config);
+        return structuredClone(history);
+    }
+
+}
+
+// PRIVATE METHODS
+
+// These are defined as standalone functions rather than class methods so as to
+// be fully private and not accessible on the instance, while still allowing
+// them to be called with the instance context (i.e., using .call(this, ...))
+// to access and modify the instance's history when necessary.
+
+/**
+ * Generates a complete configuration object for a completion request by
+ * merging the instance's default configuration with any provided overrides,
+ * and setting the appropriate response format based on the presence of a schema.
+ * @param config A configuration override for this completion request.
+ * @param stream Whether to enable streaming for this completion request.
+ * @returns The complete configuration object for the completion request.
+ * @private
+ */
+function generateCompletionConfig(config?: LlaminateConfig, stream: boolean = false): LlaminateConfig {
+    const _config = {
+        ...this.config,
+        ...config,
+        // Combine system messages from instance config and provided config
+        system: this.config.system.concat(config?.system || []),
+        options: {
+            ...this.config?.options,
+            ...config?.options,
+            stream: stream,
+            stream_options: stream ? {
+                include_usage: true // required by OpenAI
+            } : undefined
+        } as Record<string, any>
+    };
+
+    // If there are no tools delete all references, otherwise some LLMs complain
+    const tools = config?.tools || this.config?.tools || [];
+    if (tools.length > 0) {
+        _config.options.tools = tools.map(tool => ({ type: "function", function: tool.function }) );
+    } else {
+        delete _config.options.tools;
+        delete _config.options.parallel_tool_calls;
+    }
+
+    // RPM cannot be set on a per-request basis, so delete it from the override
+    delete _config.rpm;
+
+    validateConfig(_config);
+
+    if (_config.schema) {
+        _config.options.response_format = {
+            type: "json_schema",
+            json_schema: {
+                name: `schema_${uuid_v4()}`,
+                schema: _config.schema
+            }
+        };
+    }
+
+    return _config;
+}
+
+/**
+ * Validates the provided Llaminate configuration.
+ * @param config The configuration object to validate.
+ * @returns void
+ * @throws Will throw an error if the configuration is invalid.
+ * @private
+ */
+function validateConfig(config: LlaminateConfig): void {
+    if (!validate.config(config))
+        throw new Error(`The \`config\` provided to Llaminate was not a valid configuration.\n\n${ajv.errorsText(validate.config.errors)}`);
+}
+
+/**
+ * Sends a fetch request to the LLM service identified in the configuration.
+ * @param messages The messages to include in the request.
+ * @param config The configuration object for the request.
+ * @returns A promise that resolves to the fetch Response object.
+ * @private
+ */
+async function sendMessages(messages: LlaminateMessage[], config: LlaminateConfig): Promise<Response> {
+    const headers = {
+        "Authorization": `Bearer ${config.key}`,
+        "X-Api-Key": `${config.key}`,
+        "x-goog-api-key": `${config.key}`,
+        "anthropic-version": "2023-06-01",
+        "User-Agent": USER_AGENT,
+        "Content-Type": "application/json",
+        // Multiple types to handle both streaming and non-streaming responses
+        "Accept": "application/json, text/event-stream",
+        "Connection": "keep-alive",
+        ...config.headers
+    };
+
+    const body: Record<string, any> = await applyQuirks({
+        ...config.options,
+        model: config.model,
+        messages,
+    }, config);
+
+    const json = JSON.stringify(body, null, 2);
+
+    return config.fetch(config.endpoint, {
+        method: "POST",
+        headers: headers,
+        body: json,
+    });
+}
+
+/**
+ * Applies any necessary quirks to the request body based on the configuration
+ * and the target API's requirements, such as adjusting content formats,
+ * handling schema support, and modifying message structures.
+ * @param body The request body to apply quirks to.
+ * @param config The configuration object identifying quirks and other settings.
+ * @returns The modified request body with quirks applied.
+ * @private
+ */
+async function applyQuirks(body: Record<string, any>, config: LlaminateConfig): Promise<Record<string, any>> {
+
+    // First clone the body so as not to mutate the original body object. The
+    // original will have references to the instance config and other objects
+    // that we don't want to modify.
+    const modified = structuredClone(body);
+
+    // Additional system prompts to be injected (e.g. for schema instructions)
+    const instructions = [];
+
+    for (const message of modified?.messages || []) {
+
+        /**
+         * Antropic don't have the concept of a "tool" role for tool responses,
+         * instead they require tool responses to be sent with the "user" role
+         * and a specific content format, so we transform any messages with the
+         * "tool" role into the format they require if the quirk is set.
+         */
+        if (message.role === ROLE.TOOL && config.quirks?.role?.tool === false) {
+            message.role = ROLE.USER;
+            message.content = [{
+                "type": "tool_result",
+                "tool_use_id": message.tool_call_id,
+                "content": message.content
+            }];
+
+            delete message.name;
+            delete message.tool_call_id;
+        }
+
+        /**
+         * We also need to reverse that process to transform tool calls from
+         * the assistant into the format that Anthropic requires.
+         */
+        if (message.role === ROLE.ASSISTANT && message.tool_calls
+            && config.quirks?.role?.tool === false) {
+            message.content = message.tool_calls?.map((call) => ({
+                    "type": "tool_use",
+                    "id": call.id,
+                    "name": call.function.name,
+                    "input": JSON.parse(call.function.arguments),
+            }));
+
+            delete message.tool_calls;
+        }
+
+        // Content might be a string, so check before trying to iterate over it.
+        if (Array.isArray(message.content)) {
+
+            for (const content of message?.content || []) {
+
+                /**
+                 * Anthropic's API requires attachments to be sent in a unique
+                 * format using a "source" property, so if the quirk is set we
+                 * transform any content with the "image_url", "document_url",
+                 * or "file" types into the format they require.
+                 */
+                if (content.type === "image_url" && isHttpUrl(content.image_url?.url)
+                    && config.quirks?.attachments?.source === true) {
+                        content.type = "image";
+                        content.source = {
+                            type: "url",
+                            url: content.image_url.url
+                        };
+                        delete content.image_url;
+                }
+
+                if (content.type === "document_url" && isHttpUrl(content.document_url)
+                    && config.quirks?.attachments?.source === true) {
+                        content.type = "document";
+                        content.source = {
+                            type: "url",
+                            url: content.document_url
+                        };
+                        delete content.document_url;
+                }
+
+                if (["image_url", "document_url"].includes(content.type)
+                    && isBase64DataUri(content[content.type]?.url || content[content.type])
+                    && config.quirks?.attachments?.source === true) {
+                        const uri = content[content.type]?.url || content[content.type];
+                        const [meta, data] = uri.split(",");
+                        const mime = meta.match(/data:(.*);base64/)?.[1] || "application/octet-stream";
+                        content.type = mime === Llaminate.PDF ? "document" : "image";
+                        content.source = {
+                            type: "base64",
+                            data: data,
+                            media_type: mime
+                        };
+                        delete content.image_url;
+                        delete content.document_url;
+                }
+
+                /**
+                 * Google doesn't support the "document_url" content type, so
+                 * if the quirk is set we transform any content with the
+                 * document_url" type into an "image_url" (which seemingly works).
+                 */
+                if (content.type === "document_url"
+                    && config.quirks?.attachments?.document_url === "image_url") {
+                        content.type = "image_url";
+                        content.image_url = {
+                            type: "url",
+                            url: content.document_url
+                        };
+                        delete content.document_url;
+                }
+
+                /**
+                 * OpenAI's API supports a "file" content type with base64
+                 * data, so if the quirk is set we convert any "document_url"
+                 * content into that format, using the URL as the base64 data.
+                 */
+                if (content.type === "document_url"
+                    && config.quirks?.attachments?.file === true) {
+                    const data = isHttpUrl(content.document_url)
+                        ? await fetchUrlAsBase64(content.document_url)
+                        : content.document_url; // If the URL is already a data URI, we can use it directly without fetching
+
+                    content.type = "file";
+                    content.file = {
+                        file_data: data,
+                        filename: uuid_v4()
+                    };
+                    delete content.document_url;
+                }
+
+            }
+        }
+    }
+
+    modified.tools?.forEach((tool, i, tools) => {
+
+        /**
+         * Anthropic has a unique format for tools, so we transform the usual
+         * definition into the format they require.
+         */
+        if (config.quirks?.input_schema === true) {
+            tools[i] = {
+                name: tool.function.name,
+                description: tool.function.description,
+                input_schema: tool.function.parameters,
+                strict: tool.strict
+            };
+        }
+        
+    });
+
+    /**
+     * Mistral doesn't support structured output with tools, so
+     * if both a schema and tools are provided we fall back to
+     * a text response and include instructions in the system
+     * prompt.
+     */
+    if (["json_schema", "json_object"].includes(modified.response_format?.type)) {
+        if (modified.tools?.length > 0
+            && config.quirks?.tools?.json_schema === false
+            && config.quirks?.tools?.json_object === false) {
+                const schema = JSON.stringify(
+                    cleanse(modified.response_format?.json_schema), null, 2);
+                instructions.push(SYSTEM_HBS(schema));
+                modified.response_format.type = "text";
+                delete modified.response_format.json_schema;
+        }
+    }
+
+    /**
+     * Mistral and Deepseek don't support the "json_schema"
+     * response format, so if it's set in the options we
+     * convert it to a system prompt with instructions and
+     * set the content type to "json_object" instead.
+     */
+    if (modified.response_format?.type === "json_schema"
+        && config.quirks?.json_schema === false) {
+        const schema = JSON.stringify(
+            cleanse(modified.response_format?.json_schema), null, 2);
+        instructions.push(SYSTEM_HBS(schema));
+        modified.response_format.type = "json_object";
+        delete modified.response_format.json_schema;
+    }
+
+    /**
+     * Anthropic rejects tool-requests with the parallel_tool_calls property.
+     */
+    if (config.quirks?.parallel_tool_calls === false) {
+        delete modified.parallel_tool_calls;
+    }
+
+    /**
+     * Anthropic's API requires system messages to be included in the main
+     * message array with the role "system".
+     */
+    if (config.quirks?.role?.system === false) {
+        modified.system = [...instructions.map(
+            text => ({ type: "text", text: text })
+        ), ...modified.messages.filter(
+            message => message.role === ROLE.SYSTEM
+        ).map(message => ({ type: "text", text: message.content }))];
+        modified.messages = modified.messages.filter(
+            message => message.role !== ROLE.SYSTEM
+        );
+    } else {
+        modified.messages = [...instructions.map(
+            text => ({ role: ROLE.SYSTEM, content: text })
+        ), ...(modified.messages || [])];
+    }
+
+    /**
+     * Anthropic requires the "max_tokens" parameter, so we set it based on
+     * quirks if not set already.
+     */
+    if (typeof config.quirks?.max_tokens === "number") {
+        modified.max_tokens = modified.max_tokens || config.quirks?.max_tokens;
+    }
+
+    /**
+     * Anthropic doesn't support the "response_format" option and instead
+     * uses its own output_config property for structured output.
+     */
+    if (config.quirks?.output_config === true) {
+        if (modified.response_format.type === "json_schema") {
+            modified.output_config = {
+                format: {
+                    type: "json_schema",
+                    schema: modified.response_format.json_schema.schema
+                }
+            };
+        }
+
+        // Anthropic will throw an error for an unrecognized property
+        delete modified.response_format;
+    }
+
+    /**
+     * Anthropic doesn't support streaming options, and throws errors if it is
+     * included, so we remove it from the options.
+     */
+    if (config.quirks?.stream_options === false) {
+        delete modified.stream_options;
+    }
+
+    return cleanse(modified);
+}
+
+/**
+ * Transforms tool calls from the format used by Anthropic's API into the usual
+ * format expected by the rest of the code, allowing for compatibility with
+ * Anthropic's unique tool call structure.
+ * @param messages The messages from the completion response, which may contain
+ * tool calls in Anthropic's format.
+ * @returns An array of tool calls in the usual format, transformed from the
+ * provided messages.
+ * @private
+ */
+function transformAnthropicToolCalls(messages: LlaminateMessage[] | any): LlaminateMessage[] {
+    if (!Array.isArray(messages)) messages = [messages]
+    return messages?.map((message) => {
+        // Anthropic has a unique format for tool calls, so transform
+        // it into the usual format here (if present in the response)
+        if (message?.type == "tool_use") return {
+            type: "function",
+            function: {
+                name: message.name,
+                arguments: JSON.stringify(message.input)
+            },
+            id: message.id
+        }
+    }).filter(Boolean);
+};
+
+/**
+ * Merges incoming tool call deltas with existing tool calls, combining their
+ * properties based on their index.
+ * @param existing The existing tool calls.
+ * @param incoming The incoming tool call deltas.
+ * @returns The merged tool calls.
+ * @private
+ */
+function mergeToolsDeltas(existing: any[], incoming: any[] = []): Partial<LlaminateMessage["tool_calls"]>[] {
+    const merged = [...existing];
+    incoming?.forEach((delta, i) => {
+        // If there's no ID, we can't reliably merge, so skip this delta
+        if (!delta.id) return;
+
+        let found = existing.find((call) => call.id === delta.id);
+        if (!found) {
+            found = {
+                type: "",
+                function: {
+                    name: "",
+                    arguments: ""
+                },
+                id: "",
+            }
+            merged.push(found);
+        }
+        found.type += delta.type || "";
+        found.function.name += delta.function?.name || "";
+        found.function.arguments += delta.function?.arguments || "";
+        found.id += delta.id || "";
+
+        // Merge any extra_content properties (used by Google) but don't include
+        // for other APIs that don't support, which may throw an error.
+        if (delta.extra_content) {
+            found.extra_content = { ...found.extra_content, ...delta.extra_content };
+        }
+    });
+    
+    return merged;
+}
+
+/**
+ * Handles tool calls discovered in the LLM response.
+ * @param role The role of the entity calling the tools (typically "assistant").
+ * @param calls The tool calls to handle in this function.
+ * @param context The completion context for handling the tools.
+ * @returns A promise resolving to a LlaminateResponse after handling tools.
+ * @private
+ */
+async function handleTools(role: ROLE, calls: any, context: Context): Promise<LlaminateResponse> {
+    if (calls.length > 0) {
+        context.result.push({
+            role: role || ROLE.ASSISTANT,
+            tool_calls: calls.map(call => {
+                const cleansed = cleanse(call);
+                // Ensure type is set to "function" for backward compatibility
+                // with models that don't include the type in streaming deltas.
+                cleansed.type = cleansed.type || "function";
+                cleansed.function.arguments = sanatiseJSON(cleansed.function.arguments);
+                return cleansed;
+            })
+        });
+
+        for (const call of calls) {
+            const tool = context.config.tools.find((tool) => tool.function.name === call.function.name);
+            if (tool) {
+                try {
+                    // Parse the arguments and execute the tool handler, then push
+                    // the result onto the context for the next recursion.
+                    const args = JSON.parse(call.function.arguments);
+                    const response = await (tool.handler || context.config.handler || noop).call(globalThis, call.function.name, args);
+                    context.result.push({
+                        role: ROLE.TOOL,
+                        name: tool.function.name,
+                        content: serialize(response),
+                        tool_call_id: call.id,
+                    });
+                } catch (error) {
+                    // Let the LLM know the tool call failed, and include the
+                    // error message in the content. Typically the LLM will
+                    // respond to this by apologizing, but it is useful
+                    // information for the LLM to have.
+                    context.result.push({
+                        role: ROLE.TOOL,
+                        name: tool.function.name,
+                        content: JSON.stringify({ error: error.message }),
+                        tool_call_id: call.id,
+                    });
+                }
+            } else {
+                throw new Error(`The LLM response included a tool call for a tool that isn't defined in the Llaminate configuration (${call.function.name}).`);
+            }
+        };
+
+        return await context.recurse.call(this);
+    }
+}
+
+/**
+ * Extracts token usage details from a completion response.
+ * @param completion The completion response.
+ * @returns The token usage details.
+ * @private
+ */
+function getUsageFromCompletion(completion: any): Tokens {
+    const input = completion?.usage?.prompt_tokens || completion?.usage?.input_tokens || null;
+    const output = completion?.usage?.completion_tokens || completion?.usage?.output_tokens || null;
+    const total = completion?.usage?.total_tokens || null;
+    return { input: parseInt(input), output: parseInt(output), total: parseInt(total) };
+}
+
+/**
+ * Generates a LlaminateResponse in response to a finalised completion.
+ * @param message The message content.
+ * @param result The list of messages generated in this completion, including
+ * any tool calls, which is added to the instance history.
+ * @param tokens The token usage details.
+ * @param uuid A unique identifier for the response.
+ * @param config The configuration for this completion, which may affect the
+ * structure of the response (e.g. if a schema is included).
+ * @returns The generated response object.
+ * @private
+ */
+function generateOutputObject(
+    message: string | any,
+    result: LlaminateMessage[],
+    tokens: Tokens,
+    uuid: string,
+    config?: LlaminateConfig): LlaminateResponse {
+        if (config?.schema) return { message: JSON.parse(message), result, tokens, uuid };
+        else return { message, result, tokens, uuid };
+}
+
+/**
+ * Prepares a window of messages from the given prompt, modifying the message
+ * history accordingly. This function MUST be called with the Llaminate instance
+ * as its context (i.e. using .call(this, ...)) to access and modify the
+ * instance's history.
+ * @param prompt The input prompt, either a string or an array of messages.
+ * @param config The configuration containing system messages and window size.
+ * @returns A window of messages based on the history and configuration.
+ * @throws Will throw an error if the prompt is not a string or array of messages.
+ * @private
+ */
+function prepareMessageWindow(prompt: string | LlaminateMessage[], config: LlaminateConfig): LlaminateMessage[] {
+    let messages = [];
+    if (Array.isArray(prompt)) messages = getWindowFromHistory(prompt, config); // Set history to the initial messages if an array is provided
+    else if (typeof prompt === "string") messages = getWindowFromHistory(
+            this.history.concat({ role: ROLE.USER, content: prompt } as LlaminateMessage
+        ), config);
+    else throw new Error(`The \`prompt\` provided to Llaminate was not a string or an array of messages.`);
+
+    // If attachments are provided in the config, append them to the content of
+    // the last message.
+    if (config.attachments && config.attachments.length > 0) {
+        messages[messages.length - 1].content = [
+            { type: "text", text: messages[messages.length - 1].content },
+            ...config.attachments.map((attachment) => {
+                return attachment.type?.startsWith("image") ? {
+                    type: "image_url",
+                    image_url: { url: attachment.url }
+                } : {
+                    type: "document_url",
+                    document_url: attachment.url
+                };
+            })
+        ]
+    }
+
+    return messages;
+}
+
+/**
+ * Retrieves a window of messages from the history based on the configuration.
+ * @param messages The message history.
+ * @param config The configuration containing system messages and window size.
+ * @returns The filtered list of messages within the window.
+ * @private
+ */
+function getWindowFromHistory(messages: LlaminateMessage[], config: LlaminateConfig): LlaminateMessage[] {
+    let count = 0;
+    return [
+        ...(config.system || []).map(content => ({ role: ROLE.SYSTEM, content } as LlaminateMessage)),
+        ...(config.history || []), // Include any additional history provided in the config (e.g. for tools)
+        ...(messages.concat().reverse().map(message => {
+            if (message.role === ROLE.SYSTEM) return message; // Always include system messages
+            if (count < config.window) {
+                if (message.role === ROLE.USER) count++;
+                return message;
+            }
+        }).filter(Boolean).reverse())
+    ];
+}
+
+/**
+ * Updates the instance's history with the new messages based on the prompt and
+ * result. This function MUST be called with the Llaminate instance as its
+ * context (i.e. using .call(this, ...)) to access and modify the instance's
+ * history.
+ * @param prompt The original prompt, either a string or an array of messages.
+ * @param result The new messages to add to the history based on the prompt.
+ * @returns void
+ * @private
+ */
+function updateHistory(prompt: string | LlaminateMessage[], result: LlaminateMessage[]): void {
+    if (Array.isArray(prompt)) this.history = prompt.concat(result);
+    else if (typeof prompt === "string") this.history.push({
+            role: ROLE.USER, content: prompt
+        } as LlaminateMessage, ...result);
+}
+
+/**
+ * Recursively "cleanses" an object, recursively removing null properties and
+ * ensuring that any nested objects are also cleansed.
+ * @param obj The object to be "cleansed".
+ * @returns The "cleansed" object.
+ * @private
+ */
+function cleanse(obj: Record<string, any>): Record<string, any> {
+    if (obj && obj.constructor !== Object) return Object.entries(obj).reduce((acc, [key, value]) => {
+        if (value === null) {
+            // Skip null properties
+            return acc;
+        } else if (typeof value === "object" && !Array.isArray(value) && value !== null) {
+            // Recursively cleanse nested objects
+            acc[key] = cleanse(value);
+        } else {
+            acc[key] = value;
+        }
+        return acc;
+    }, {} as Record<string, any>);
+    else return obj;
+}
+
+/**
+ * Validates a LLM response against a schema provided in the configuration. If a
+ * schema is present, it attempts to parse the message as JSON and validate it
+ * against the schema. If no schema is present, it checks the message is not
+ * empty and returns it as is.
+ * @param message The response message to validate.
+ * @param config The configuration containing the schema for validation.
+ * @returns The validated message as a string.
+ * @throws Will throw an error if the message does not conform to the schema or
+ * if the message is empty.
+ * @private
+ */
+function validateResponse(message:string, config: LlaminateConfig):string {
+    if (config.schema) {
+        const json:string = sanatiseJSON(message);
+        const obj:any = JSON.parse(json);
+
+        const schema = ajv.compile(config.schema);
+        const valid:any = schema(obj);
+        if (!valid) throw new Error(`The LLM response did not conform to the \`schema\` provided in the Llaminate configuration.\n\n${ajv.errorsText(schema.errors)}`);
+
+        return JSON.stringify(obj);
+    } else if (message) return message;
+    else throw new Error("The LLM response was empty.");
+}
+
+/**
+ * Serializes an object to a JSON string, with error handling for
+ * non-serializable objects (e.g. BigInt).
+ * @param obj The object to serialize.
+ * @returns A JSON representation of the object.
+ * @throws Will throw an error if the object cannot be serialized to JSON.
+ * @private
+ */
+function serialize(obj: any): string {
+    try {
+        return JSON.stringify(obj);
+    } catch (error) {
+        try {
+            // Handle non-serializable objects by trying to convert them to
+            // strings, if they have a toString method. This is a best effort
+            // attempt to provide some information about the object (as opposed 
+            // to [object Object] or throwing an error).
+            if (obj && typeof obj.toString === "function") {
+                const str = obj.toString();
+                if (typeof str === "string") return JSON.stringify(str);
+            }
+        } catch (error) { /* meh, didn't work */ }
+
+        // This will be handled by the caller (which was trying to parse a tool
+        // response) and returned as an error message to the LLM.
+        throw error;
+    }
+}
+
+/**
+ * Generates a UUIDv4 string.
+ * @returns A UUIDv4 string.
+ * @private
+ */
+function uuid_v4(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+        const r = Math.random() * 16 | 0, v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}
+
+/**
+ * Deeply freezes an object, making it immutable by recursively freezing all
+ * nested objects and arrays.
+ * @param obj The object to be deeply frozen.
+ * @returns The deeply frozen object.
+ * @private
+ */
+function deepFreeze(obj: any): any {
+    const props = Object.getOwnPropertyNames(obj);
+    for (const name of props) {
+        const value = obj[name];
+        if (value && typeof value === "object") deepFreeze(value);
+    }
+
+    return Object.freeze(obj);
+}
+
+/**
+ * Sanitises a JSON string by extracting the JSON object from the string and
+ * ensuring it is valid JSON. This is necessary because some models may return
+ * JSON responses wrapped in additional text or formatting.
+ * @param json The JSON string to sanitise.
+ * @returns The sanitised JSON string.
+ * @throws Will throw an error if the sanitised string is not valid JSON and
+ * cannot be parsed or repaired.
+ * @private
+ */
+function sanatiseJSON(json: string): string {
+    try {
+        // Extract the JSON object from the string, or default to an empty
+        // object if no JSON-like structure is found.
+        const match = json.match(/{.*}/s)?.[0] || "{}";
+        // Try to parse the JSON to ensure it's valid.
+        JSON.parse(match);
+        return match;
+    } catch (error) {
+        throw new Error(`The LLM response could not be parsed as JSON.\n\n${json}`);
+    }
+}
+
+/**
+ * Defines specific quirks or requirements for different AI services endpoints,
+ * such as how to format images URLs, etc.. Typically it is the options property
+ * in the configuration object that will need to be modified based on these.
+ * @param config The configuration object to determine the endpoint.
+ * @returns An object containing an object of properties with boolean and string
+ * flags indicating different "quirks" to handle for different endpoints.
+ * @private
+ */
+function getQuirks(config: LlaminateConfig): LlaminateQuirks {
+    const endpoint = config.endpoint;
+
+    const isMistral = endpoint.startsWith(Llaminate.MISTRAL);
+    const isOpenAI = endpoint.startsWith(Llaminate.OPENAI);
+    const isGoogle = endpoint.startsWith(Llaminate.GOOGLE);
+    const isDeepSeek = endpoint.startsWith(Llaminate.DEEPSEEK);
+    const isAnthropic = endpoint.startsWith(Llaminate.ANTHROPIC);
+
+    return {
+        attachments: {
+            // Google doesn't support the "document_url" content type, but we
+            // can transform it into an "image_url" (which seemingly works).
+            document_url: isGoogle ? "image_url" : undefined,
+            // Anthropic uses a "source" stynax for attachements instead of the
+            // standard content array with "image_url".
+            source: isAnthropic,
+            // OpenAI on the other hand uses a "file" content type with base64
+            // data for PDF files.
+            file: isOpenAI
+        },
+        // Anthropic use an "input_schema" property for the arguments accepted
+        // by tools.
+        input_schema: isAnthropic,
+        // DeepSeek doesn't support json_schema (and Mistral misbehaves), so we
+        // fall back to using instructions in the system prompt and json_object.
+        json_schema: !isDeepSeek && !isMistral,
+        // Anthropic requires max_tokens in every call, so set this to a
+        // maximum for the smallest model used by them.
+        max_tokens: isAnthropic ? 64000 : undefined,
+        // Anthropic uses "output_config" instead of "response_format"
+        output_config: isAnthropic,
+        // Anthropic complains if the parallel_tool_calls property is included,
+        // even though it supports parallel tool calls.
+        parallel_tool_calls: !isAnthropic,
+        role: {
+            // Anthropic doesn't support the "system" role for system messages,
+            // and instead requires these to be included as a separate "system"
+            // property in the request body.
+            system: !isAnthropic,
+            // Anthropic doesn't support the "tool" role for tool responses, and
+            // instead the responses are sent back by the "user".
+            tool: !isAnthropic
+        },
+        // OpenAI requires the stream_options property to send back tokens, but
+        // Anthropic complains if this is included.
+        stream_options: !isAnthropic,
+        tools: {
+            // Mistral misbehaves with streaming with tools and structured
+            // output, so disable both modes of structured output and rely on
+            // text output with instructions in the system prompt instead.
+            json_schema: !isMistral,
+            json_object: !isMistral
+        },
+    };
+}
+
+/**
+ * Fetches a file from the given URL and returns its content as a base64-encoded
+ * string. This is to handle file URLs that need to be sent in base64 format,
+ * such as when using OpenAI's file API for PDFs.
+ * @param url The URL of the file to fetch and encode.
+ * @returns A promise that resolves to the base64-encoded string of the file's
+ * content.
+ * @throws Will throw an error if the fetch request fails or if there is an
+ * issue reading the file.
+ * @private
+ */
+async function fetchUrlAsBase64(url: string): Promise<string> {
+    const response = await fetch(url, { headers: { "User-Agent": USER_AGENT } });
+
+    if (!response.ok) { throw new Error(`HTTP status ${response.status} from ${url}.\n\n${await response.text()}`); }
+
+    try {
+        const buffer = await response.arrayBuffer();
+        const base64 = Buffer.from(buffer).toString("base64");
+
+        const type = response.headers.get("content-type") || "application/octet-stream";
+        return `data:${type};base64,${base64}`;
+    } catch (error) {
+        throw new Error(`Failed to encode from ${url} as base64.\n\n${error.message}`);
+    }
+}
+
+/**
+ * Checks if a given URL is an HTTP or HTTPS URL.
+ * @param url The URL string to check.
+ * @returns A Boolean true if the URL is an HTTP or HTTPS URL, false otherwise.
+ * @private
+ */
+function isHttpUrl(url: string): boolean {
+    try {
+        const parsed = new URL(url);
+        return ["http:", "https:"].includes(parsed.protocol);
+    } catch (error) {
+        return false;
+    }
+}
+
+/**
+ * Checks if a given URI is a base64 data URI.
+ * @param uri The URI string to check.
+ * @returns A Boolean true if the URI is a base64 data URI, false otherwise.
+ * @private
+ */
+function isBase64DataUri(uri: string): boolean {
+    return /^data:.*;base64,/.test(uri);
+}