@jaypie/llm 1.1.26 → 1.1.27

package/dist/esm/providers/openai/utils.d.ts

@@ -0,0 +1,59 @@
+import { log as defaultLog } from "@jaypie/core";
+import { JsonObject, NaturalSchema } from "@jaypie/types";
+import { OpenAI } from "openai";
+import { z } from "zod/v4";
+import { LlmMessageOptions } from "../../types/LlmProvider.interface.js";
+export declare const getLogger: () => {
+    debug: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    error: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    fatal: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    info: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    trace: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    warn: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    var(key: string | Record<string, unknown>, value?: unknown): void;
+    with(tags: Record<string, unknown>): typeof defaultLog;
+    tag(key: string | string[] | Record<string, unknown> | null, value?: string): void;
+    untag(tags: string | string[] | Record<string, unknown> | null): void;
+    lib(options: {
+        level?: string;
+        lib?: string;
+        tags?: Record<string, unknown>;
+    }): typeof defaultLog;
+};
+export declare function initializeClient({ apiKey, }?: {
+    apiKey?: string;
+}): Promise<OpenAI>;
+export interface ChatMessage {
+    role: "user" | "developer";
+    content: string;
+}
+export declare function formatSystemMessage(systemPrompt: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): ChatMessage;
+export declare function formatUserMessage(message: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): ChatMessage;
+export declare function prepareMessages(message: string, { system, data, placeholders }?: LlmMessageOptions): ChatMessage[];
+export declare function createStructuredCompletion(client: OpenAI, { messages, responseSchema, model, }: {
+    messages: ChatMessage[];
+    responseSchema: z.ZodType | NaturalSchema;
+    model: string;
+}): Promise<JsonObject>;
+export declare function createTextCompletion(client: OpenAI, { messages, model, }: {
+    messages: ChatMessage[];
+    model: string;
+}): Promise<string>;

package/dist/esm/tools/Toolkit.class.d.ts

@@ -0,0 +1,28 @@
+import { LlmTool } from "../types/LlmTool.interface";
+type LogFunction = (message: string, context: {
+    name: string;
+    args: any;
+}) => void | Promise<void>;
+export interface ToolkitOptions {
+    explain?: boolean;
+    log?: boolean | LogFunction;
+}
+export declare class Toolkit {
+    private readonly _tools;
+    private readonly _options;
+    private readonly explain;
+    private readonly log;
+    constructor(tools: LlmTool[], options?: ToolkitOptions);
+    get tools(): Omit<LlmTool, "call">[];
+    call({ name, arguments: args }: {
+        name: string;
+        arguments: string;
+    }): Promise<import("@jaypie/types").AnyValue>;
+    extend(tools: LlmTool[], options?: {
+        warn?: boolean;
+        replace?: boolean;
+        log?: boolean | LogFunction;
+        explain?: boolean;
+    }): this;
+}
+export {};

package/dist/esm/tools/index.d.ts

@@ -0,0 +1,12 @@
+import { Toolkit } from "./Toolkit.class.js";
+import type { LlmTool } from "../types/LlmTool.interface.js";
+export declare const tools: LlmTool[];
+export declare class JaypieToolkit extends Toolkit {
+    readonly random: LlmTool;
+    readonly roll: LlmTool;
+    readonly time: LlmTool;
+    readonly weather: LlmTool;
+    constructor(tools: LlmTool[], options?: any);
+}
+export declare const toolkit: JaypieToolkit;
+export { Toolkit };

package/dist/esm/tools/random.d.ts

@@ -0,0 +1,2 @@
+import { LlmTool } from "../types/LlmTool.interface.js";
+export declare const random: LlmTool;

package/dist/esm/tools/roll.d.ts

@@ -0,0 +1,2 @@
+import { LlmTool } from "../types/LlmTool.interface.js";
+export declare const roll: LlmTool;

package/dist/esm/tools/time.d.ts

@@ -0,0 +1,2 @@
+import { LlmTool } from "../types/LlmTool.interface.js";
+export declare const time: LlmTool;

package/dist/esm/tools/weather.d.ts

@@ -0,0 +1,2 @@
+import { LlmTool } from "../types/LlmTool.interface.js";
+export declare const weather: LlmTool;

package/dist/esm/types/LlmProvider.interface.d.ts

@@ -0,0 +1,198 @@
+import { AnyValue, JsonObject, JsonReturn, NaturalMap, NaturalSchema } from "@jaypie/types";
+import { z } from "zod/v4";
+import { LlmTool } from "./LlmTool.interface.js";
+import { Toolkit } from "../tools/Toolkit.class.js";
+export declare enum LlmMessageRole {
+    Assistant = "assistant",
+    Developer = "developer",
+    System = "system",
+    User = "user"
+}
+export declare enum LlmMessageType {
+    FunctionCall = "function_call",
+    FunctionCallOutput = "function_call_output",
+    InputFile = "input_file",
+    InputImage = "input_image",
+    InputText = "input_text",
+    ItemReference = "item_reference",
+    Message = "message",
+    OutputText = "output_text",
+    Refusal = "refusal"
+}
+export declare enum LlmResponseStatus {
+    Completed = "completed",
+    Incomplete = "incomplete",
+    InProgress = "in_progress"
+}
+interface LlmError {
+    detail?: string;
+    status: number | string;
+    title: string;
+}
+export interface LlmInputContentFile {
+    type: LlmMessageType.InputFile;
+    file_data: File | string;
+    file_id?: string;
+    filename?: string;
+}
+export interface LlmInputContentImage {
+    type: LlmMessageType.InputImage;
+    detail?: File;
+    file_id?: string;
+    image_url?: string;
+}
+export interface LlmInputContentText {
+    type: LlmMessageType.InputText;
+    text: string;
+}
+export type LlmInputContent = LlmInputContentFile | LlmInputContentImage | LlmInputContentText;
+/**
+ * Represents the "Input message object" in the "input item list"
+ * from [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses/create)
+ */
+export interface LlmInputMessage {
+    content: string | Array<LlmInputContent>;
+    role: LlmMessageRole;
+    type?: LlmMessageType.Message;
+}
+export interface LlmOutputContentText {
+    annotations?: AnyValue[];
+    text: string;
+    type: LlmMessageType.OutputText;
+}
+interface LlmOutputRefusal {
+    refusal: string;
+    type: LlmMessageType.Refusal;
+}
+type LlmOutputContent = LlmOutputContentText | LlmOutputRefusal;
+/**
+ * Represents the "Output message object" in the "input item list"
+ * from [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses/create)
+ */
+export interface LlmOutputMessage {
+    content: string | Array<LlmOutputContent>;
+    id?: string;
+    role: LlmMessageRole.Assistant;
+    status?: LlmResponseStatus;
+    type?: LlmMessageType.Message;
+}
+type LlmOutputItem = LlmToolCall | LlmToolResult | LlmOutputMessage;
+type LlmOutput = LlmOutputItem[];
+export interface LlmToolCall {
+    arguments: string;
+    call_id: string;
+    id: string;
+    name: string;
+    type: LlmMessageType.FunctionCall;
+    status: LlmResponseStatus;
+}
+export interface LlmToolResult {
+    call_id: string;
+    output: string;
+    status?: LlmResponseStatus;
+    type: LlmMessageType.FunctionCallOutput;
+}
+interface LlmItemReference {
+    type: LlmMessageType.ItemReference;
+    id: string;
+}
+export type LlmHistoryItem = LlmInputMessage | LlmItemReference | LlmOutputItem | LlmToolResult;
+export type LlmHistory = LlmHistoryItem[];
+export interface LlmMessageOptions {
+    data?: NaturalMap;
+    model?: string;
+    placeholders?: {
+        message?: boolean;
+        system?: boolean;
+    };
+    response?: NaturalSchema | z.ZodType;
+    system?: string;
+}
+export interface LlmOperateOptions {
+    data?: NaturalMap;
+    explain?: boolean;
+    format?: JsonObject | NaturalSchema | z.ZodType;
+    history?: LlmHistory;
+    hooks?: {
+        afterEachModelResponse?: ({ input, options, providerRequest, providerResponse, content, usage, }: {
+            input: string | LlmHistory | LlmInputMessage;
+            options?: LlmOperateOptions;
+            providerRequest: any;
+            providerResponse: any;
+            content: string | JsonObject;
+            usage: LlmUsage;
+        }) => unknown | Promise<unknown>;
+        afterEachTool?: ({ result, toolName, args, }: {
+            result: unknown;
+            toolName: string;
+            args: string;
+        }) => unknown | Promise<unknown>;
+        beforeEachModelRequest?: ({ input, options, providerRequest, }: {
+            input: string | LlmHistory | LlmInputMessage;
+            options?: LlmOperateOptions;
+            providerRequest: any;
+        }) => unknown | Promise<unknown>;
+        beforeEachTool?: ({ toolName, args, }: {
+            toolName: string;
+            args: string;
+        }) => unknown | Promise<unknown>;
+        onRetryableModelError?: ({ input, options, providerRequest, error, }: {
+            input: string | LlmHistory | LlmInputMessage;
+            options?: LlmOperateOptions;
+            providerRequest: any;
+            error: any;
+        }) => unknown | Promise<unknown>;
+        onToolError?: ({ error, toolName, args, }: {
+            error: Error;
+            toolName: string;
+            args: string;
+        }) => unknown | Promise<unknown>;
+        onUnrecoverableModelError?: ({ input, options, providerRequest, error, }: {
+            input: string | LlmHistory | LlmInputMessage;
+            options?: LlmOperateOptions;
+            providerRequest: any;
+            error: any;
+        }) => unknown | Promise<unknown>;
+    };
+    instructions?: string;
+    model?: string;
+    placeholders?: {
+        input?: boolean;
+        instructions?: boolean;
+        system?: boolean;
+    };
+    providerOptions?: JsonObject;
+    system?: string;
+    tools?: LlmTool[] | Toolkit;
+    turns?: boolean | number;
+    user?: string;
+}
+export interface LlmOptions {
+    apiKey?: string;
+    model?: string;
+}
+export interface LlmUsageItem {
+    input: number;
+    output: number;
+    reasoning: number;
+    total: number;
+    provider?: string;
+    model?: string;
+}
+export type LlmUsage = LlmUsageItem[];
+export interface LlmOperateResponse {
+    content?: string | JsonObject;
+    error?: LlmError;
+    history: LlmHistory;
+    model?: string;
+    output: LlmOutput;
+    provider?: string;
+    responses: JsonReturn[];
+    status: LlmResponseStatus;
+    usage: LlmUsage;
+}
+export interface LlmProvider {
+    operate?(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
+    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+}
+export {};

package/dist/esm/types/LlmTool.interface.d.ts

@@ -0,0 +1,11 @@
+import { AnyValue, JsonObject } from "@jaypie/types";
+export interface LlmTool {
+    description: string;
+    name: string;
+    parameters: JsonObject;
+    type: "function" | string;
+    call: (args?: JsonObject) => Promise<AnyValue> | AnyValue;
+    message?: string | ((args?: JsonObject, context?: {
+        name: string;
+    }) => Promise<string> | string);
+}

package/dist/esm/util/determineModelProvider.d.ts

@@ -0,0 +1,4 @@
+export declare function determineModelProvider(input?: string): {
+    model: string;
+    provider?: string;
+};

package/dist/esm/util/formatOperateInput.d.ts

@@ -0,0 +1,24 @@
+import { LlmHistory, LlmInputMessage, LlmMessageRole } from "../types/LlmProvider.interface.js";
+import { NaturalMap } from "@jaypie/types";
+/**
+ * Options for formatOperateInput function
+ */
+export interface FormatOperateInputOptions {
+    /**
+     * Data to use for placeholder substitution
+     */
+    data?: NaturalMap;
+    /**
+     * Role to use when converting a string to LlmInputMessage
+     */
+    role?: LlmMessageRole;
+}
+/**
+ * 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
+ */
+export declare function formatOperateInput(input: string | LlmInputMessage | LlmHistory, options?: FormatOperateInputOptions): LlmHistory;

package/dist/esm/util/formatOperateMessage.d.ts

@@ -0,0 +1,24 @@
+import { LlmInputMessage, LlmMessageRole } from "../types/LlmProvider.interface.js";
+import { NaturalMap } from "@jaypie/types";
+/**
+ * Options for formatOperateMessage function
+ */
+export interface FormatOperateMessageOptions {
+    /**
+     * Data to use for placeholder substitution
+     */
+    data?: NaturalMap;
+    /**
+     * Role to use for the message
+     */
+    role?: LlmMessageRole;
+}
+/**
+ * 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
+ */
+export declare function formatOperateMessage(input: string, options?: FormatOperateMessageOptions): LlmInputMessage;

package/dist/esm/util/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./determineModelProvider.js";
+export * from "./formatOperateInput.js";
+export * from "./formatOperateMessage.js";
+export * from "./logger.js";
+export * from "./maxTurnsFromOptions.js";
+export * from "./naturalZodSchema.js";
+export * from "./random.js";
+export * from "./tryParseNumber.js";

package/dist/esm/util/logger.d.ts

@@ -0,0 +1,71 @@
+import { log as defaultLog } from "@jaypie/core";
+export declare const getLogger: () => {
+    debug: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    error: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    fatal: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    info: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    trace: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    warn: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    var(key: string | Record<string, unknown>, value?: unknown): void;
+    with(tags: Record<string, unknown>): typeof defaultLog;
+    tag(key: string | string[] | Record<string, unknown> | null, value?: string): void;
+    untag(tags: string | string[] | Record<string, unknown> | null): void;
+    lib(options: {
+        level?: string;
+        lib?: string;
+        tags?: Record<string, unknown>;
+    }): typeof defaultLog;
+};
+export declare const log: {
+    debug: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    error: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    fatal: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    info: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    trace: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    warn: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    var(key: string | Record<string, unknown>, value?: unknown): void;
+    with(tags: Record<string, unknown>): typeof defaultLog;
+    tag(key: string | string[] | Record<string, unknown> | null, value?: string): void;
+    untag(tags: string | string[] | Record<string, unknown> | null): void;
+    lib(options: {
+        level?: string;
+        lib?: string;
+        tags?: Record<string, unknown>;
+    }): typeof defaultLog;
+};

package/dist/esm/util/maxTurnsFromOptions.d.ts

@@ -0,0 +1,10 @@
+import { LlmOperateOptions } from "../types/LlmProvider.interface.js";
+export declare const MAX_TURNS_ABSOLUTE_LIMIT = 72;
+export declare 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
+ */
+export declare function maxTurnsFromOptions(options: LlmOperateOptions): number;

package/dist/esm/util/naturalZodSchema.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod/v4";
+import { NaturalSchema } from "@jaypie/types";
+export declare function naturalZodSchema(definition: NaturalSchema): z.ZodTypeAny;

package/dist/esm/util/random.d.ts

@@ -0,0 +1,39 @@
+interface RandomOptions {
+    min?: number;
+    max?: number;
+    mean?: number;
+    stddev?: number;
+    integer?: boolean;
+    start?: number;
+    seed?: string;
+    precision?: number;
+    currency?: boolean;
+}
+type RandomFunction = {
+    (options?: RandomOptions): number;
+};
+export declare const DEFAULT_MIN = 0;
+export declare const DEFAULT_MAX = 1;
+/**
+ * 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" });
+ */
+export declare function random(defaultSeed?: string): RandomFunction;
+export {};

package/dist/esm/util/tryParseNumber.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Options for tryParseNumber function
+ */
+export interface TryParseNumberOptions {
+    /**
+     * Default value to return if parsing fails or results in NaN
+     */
+    defaultValue?: number;
+    /**
+     * Function to call with warning message if parsing fails or results in NaN
+     */
+    warnFunction?: (message: string) => void;
+}
+/**
+ * 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
+ */
+export declare function tryParseNumber(input: unknown, options?: TryParseNumberOptions): number | unknown;

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@jaypie/llm",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "description": "Large language model utilities",
   "license": "MIT",
   "author": "Finlayson Studio",
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
     }
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
   "files": [
     "dist"
   ],
@@ -41,5 +43,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c4a4f52f239792e51dacaa9460874931b54b0d65"
+  "gitHead": "0e8414490636bbda8f9f21bd2946d391500318a5"
 }