mdi-llmkit 1.0.1 → 1.0.6

package/dist/tests/comparison/compareLists.test.js

@@ -35,16 +35,16 @@ const assertProcessedCountersAreSequential = (events) => {
         expect(finishes[finishes.length - 1].totalLeftToProcess).toBe(0);
     }
 };
-describe.concurrent('compareItemLists (live API)', () => {
+describe('compareItemLists (live API)', () => {
     // IMPORTANT: These tests intentionally use live OpenAI calls and DO NOT mock GptConversation.
     // We are validating the real prompt+schema behavior end-to-end (including model decisions),
     // not just local control-flow in isolation.
-    describe.concurrent('input validation', () => {
+    describe('input validation', () => {
         it('throws for duplicate item names (case-insensitive) within a list', async () => {
             await expect(compareItemLists(createClient(), ['Widget', 'widget'], ['Other'])).rejects.toThrow('Duplicate item names found in before list');
         });
     });
-    describe.concurrent('string behavior', () => {
+    describe('string behavior', () => {
         it('classifies case-insensitive exact string matches as unchanged', async () => {
             const { events, callback } = collectEvents();
             const result = await compareItemLists(createClient(), ['String Item A', 'String Item B'], ['string item a', 'STRING ITEM B'], 'Case-only differences are unchanged.', callback);
@@ -56,7 +56,7 @@ describe.concurrent('compareItemLists (live API)', () => {
             expect(events).toHaveLength(0);
         }, 180000);
     });
-    describe.concurrent('name/description behavior', () => {
+    describe('name/description behavior', () => {
         it('treats same names as unchanged even when descriptions differ', async () => {
             const result = await compareItemLists(createClient(), [
                 {
@@ -94,7 +94,7 @@ describe.concurrent('compareItemLists (live API)', () => {
             expect(result.renamed['Plan Bronze Legacy']).toBe('Plan Bronze Modern');
         }, 180000);
     });
-    describe.concurrent('rename behavior', () => {
+    describe('rename behavior', () => {
         it('detects a single guided rename', async () => {
             const result = await compareItemLists(createClient(), ['ACME Legacy Plan'], ['ACME Modern Plan'], 'There is exactly one rename in this migration. ' +
                 'ACME Legacy Plan was renamed to ACME Modern Plan. ' +
@@ -120,7 +120,7 @@ describe.concurrent('compareItemLists (live API)', () => {
             expect(result.unchanged).toEqual([]);
         }, 180000);
     });
-    describe.concurrent('added/deleted behavior', () => {
+    describe('added/deleted behavior', () => {
         it('classifies explicit deletion', async () => {
             const result = await compareItemLists(createClient(), ['Delete Me Item'], [], 'Delete Me Item was intentionally removed and has no replacement.');
             expect(result.removed).toEqual(['Delete Me Item']);
@@ -136,7 +136,7 @@ describe.concurrent('compareItemLists (live API)', () => {
             expect(result.unchanged).toEqual([]);
         }, 180000);
     });
-    describe.concurrent('mixed outcomes', () => {
+    describe('mixed outcomes', () => {
         it('handles unchanged + renamed + removed + added together', async () => {
             const result = await compareItemLists(createClient(), ['Shared Constant Item', 'Legacy Rename Target', 'Delete Candidate'], ['shared constant item', 'Modern Rename Target', 'Add Candidate'], 'Legacy Rename Target was renamed to Modern Rename Target. ' +
                 'Delete Candidate was removed. ' +
@@ -148,7 +148,7 @@ describe.concurrent('compareItemLists (live API)', () => {
             expect(result.added).toEqual(['Add Candidate']);
         }, 180000);
     });
-    describe.concurrent('callback reporting behavior', () => {
+    describe('callback reporting behavior', () => {
         it('emits balanced start/finish events with correct source-list flags', async () => {
             const { events, callback } = collectEvents();
             await compareItemLists(createClient(), ['Before Removed A', 'Before Removed B'], ['After Added A'], 'Before Removed A and Before Removed B were removed. ' +
@@ -192,7 +192,7 @@ describe.concurrent('compareItemLists (live API)', () => {
             expect(finishEventsWithErrors.some((event) => (event.error || '').includes('LLM processing failed'))).toBe(true);
         }, 180000);
     });
-    describe.concurrent('bulk list scenarios', () => {
+    describe('bulk list scenarios', () => {
         it('handles a larger mixed migration with multiple renames/additions/deletions', async () => {
             const beforeItems = [
                 'Shared Stable A',
@@ -269,7 +269,7 @@ describe.concurrent('compareItemLists (live API)', () => {
             assertProcessedCountersAreSequential(events);
         }, 240000);
     });
-    describe.concurrent('inference without explicit mapping instructions', () => {
+    describe('inference without explicit mapping instructions', () => {
         it('infers removed string items when after list omits them', async () => {
             const result = await compareItemLists(createClient(), [
                 'Invoice Number',
@@ -299,10 +299,10 @@ describe.concurrent('compareItemLists (live API)', () => {
                 'Subtotal',
                 'Order Date',
                 'Shipping Method',
-                'Tracking Number',
+                'Delivery Address',
             ]);
             expect(result.removed).toEqual([]);
-            expect(result.added).toEqual(['Shipping Method', 'Tracking Number']);
+            expect(result.added?.sort()).toEqual(['Delivery Address', 'Shipping Method']);
             expect(result.renamed).toEqual({});
             expect(result.unchanged).toEqual([
                 'Customer Name',

package/dist/tests/jsonSurgery/jsonSurgery.test.js

@@ -8,7 +8,7 @@ if (!OPENAI_API_KEY) {
 const createClient = () => new OpenAI({
     apiKey: OPENAI_API_KEY,
 });
-describe.concurrent('jsonSurgery (live API)', () => {
+describe('jsonSurgery (live API)', () => {
     describe('atomic operations', () => {
         it('applies a simple scalar update without mutating original input', async () => {
             const original = {

package/package.json

@@ -1,53 +1,57 @@
-{
-  "name": "mdi-llmkit",
-  "version": "1.0.1",
-  "description": "Utilities for managing multi-shot conversations and structured data handling in LLM applications",
-  "author": "Mikhail Voloshin",
-  "license": "MIT",
-  "type": "module",
-  "sideEffects": false,
-  "main": "dist/src/index.js",
-  "types": "dist/src/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/src/index.d.ts",
-      "import": "./dist/src/index.js"
-    },
-    "./gptApi": {
-      "types": "./dist/src/gptApi/index.d.ts",
-      "import": "./dist/src/gptApi/index.js"
-    },
-    "./jsonSurgery": {
-      "types": "./dist/src/jsonSurgery/jsonSurgery.d.ts",
-      "import": "./dist/src/jsonSurgery/jsonSurgery.js"
-    },
-    "./comparison": {
-      "types": "./dist/src/comparison/index.d.ts",
-      "import": "./dist/src/comparison/index.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "prepublishOnly": "npm run test && npm run build"
-  },
-  "keywords": [
-    "llm",
-    "openai",
-    "responses-api",
-    "structured-outputs",
-    "chat"
-  ],
-  "dependencies": {
-    "dotenv": "^17.3.1",
-    "openai": "^6.2.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.18.10",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "mdi-llmkit",
+  "version": "1.0.6",
+  "description": "Utilities for managing multi-shot conversations and structured data handling in LLM applications",
+  "author": "Mikhail Voloshin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mighty-Data-Inc/mdi-llmkit"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./gptApi": {
+      "types": "./dist/src/gptApi/index.d.ts",
+      "import": "./dist/src/gptApi/index.js"
+    },
+    "./jsonSurgery": {
+      "types": "./dist/src/jsonSurgery/jsonSurgery.d.ts",
+      "import": "./dist/src/jsonSurgery/jsonSurgery.js"
+    },
+    "./comparison": {
+      "types": "./dist/src/comparison/index.d.ts",
+      "import": "./dist/src/comparison/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "keywords": [
+    "llm",
+    "openai",
+    "responses-api",
+    "structured-outputs",
+    "chat"
+  ],
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "openai": "^6.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.10",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/dist/gpt_api/functions.d.ts

@@ -1,25 +0,0 @@
-export declare const GPT_MODEL_CHEAP = "gpt-4.1-nano";
-export declare const GPT_MODEL_SMART = "gpt-4.1";
-export interface OpenAIClientLike {
-    responses: {
-        create: (args: {
-            model: string;
-            input: unknown[];
-            text?: Record<string, unknown>;
-        }) => Promise<any> | any;
-    };
-}
-export interface SystemMessage {
-    role: "system";
-    content: string;
-}
-export interface GptSubmitOptions {
-    model?: string;
-    jsonResponse?: boolean | Record<string, unknown> | string;
-    systemAnnouncementMessage?: string;
-    retryLimit?: number;
-    retryBackoffTimeSeconds?: number;
-    warningCallback?: (message: string) => void;
-}
-export declare function currentDatetimeSystemMessage(): SystemMessage;
-export declare function gptSubmit(messages: unknown[], openaiClient: OpenAIClientLike, options?: GptSubmitOptions): Promise<string | Record<string, unknown> | unknown[] | number | boolean | null>;

package/dist/gpt_api/functions.js

@@ -1,193 +0,0 @@
-export const GPT_MODEL_CHEAP = "gpt-4.1-nano";
-export const GPT_MODEL_SMART = "gpt-4.1";
-const GPT_RETRY_LIMIT_DEFAULT = 5;
-const GPT_RETRY_BACKOFF_TIME_SECONDS_DEFAULT = 30;
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function parseFirstJsonValue(input) {
-    const text = input.trimStart();
-    if (!text) {
-        throw new SyntaxError("Unexpected end of JSON input");
-    }
-    const first = text[0];
-    if (first === "{" || first === "[") {
-        const closing = first === "{" ? "}" : "]";
-        let depth = 0;
-        let inString = false;
-        let escaped = false;
-        for (let index = 0; index < text.length; index += 1) {
-            const char = text[index];
-            if (inString) {
-                if (escaped) {
-                    escaped = false;
-                    continue;
-                }
-                if (char === "\\") {
-                    escaped = true;
-                    continue;
-                }
-                if (char === '"') {
-                    inString = false;
-                }
-                continue;
-            }
-            if (char === '"') {
-                inString = true;
-                continue;
-            }
-            if (char === first) {
-                depth += 1;
-            }
-            else if (char === closing) {
-                depth -= 1;
-                if (depth === 0) {
-                    return JSON.parse(text.slice(0, index + 1));
-                }
-            }
-        }
-        throw new SyntaxError("Unexpected end of JSON input");
-    }
-    if (first === '"') {
-        let escaped = false;
-        for (let index = 1; index < text.length; index += 1) {
-            const char = text[index];
-            if (escaped) {
-                escaped = false;
-                continue;
-            }
-            if (char === "\\") {
-                escaped = true;
-                continue;
-            }
-            if (char === '"') {
-                return JSON.parse(text.slice(0, index + 1));
-            }
-        }
-        throw new SyntaxError("Unexpected end of JSON input");
-    }
-    if (text.startsWith("true")) {
-        return true;
-    }
-    if (text.startsWith("false")) {
-        return false;
-    }
-    if (text.startsWith("null")) {
-        return null;
-    }
-    const numberMatch = text.match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/);
-    if (numberMatch) {
-        return JSON.parse(numberMatch[0]);
-    }
-    throw new SyntaxError("Unexpected token in JSON input");
-}
-function isRetryableOpenAIError(error) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    const name = error.name || "";
-    return name.includes("OpenAI") || name.includes("APIError");
-}
-export function currentDatetimeSystemMessage() {
-    const now = new Date();
-    const pad = (value) => value.toString().padStart(2, "0");
-    const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
-        `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
-    return {
-        role: "system",
-        content: `!DATETIME: The current date and time is ${timestamp}`,
-    };
-}
-export async function gptSubmit(messages, openaiClient, options = {}) {
-    const model = options.model || GPT_MODEL_SMART;
-    const retryLimit = options.retryLimit ?? GPT_RETRY_LIMIT_DEFAULT;
-    const retryBackoffTimeSeconds = options.retryBackoffTimeSeconds ?? GPT_RETRY_BACKOFF_TIME_SECONDS_DEFAULT;
-    let failedError = null;
-    let openaiTextParam;
-    if (options.jsonResponse) {
-        if (typeof options.jsonResponse === "boolean") {
-            openaiTextParam = { format: { type: "json_object" } };
-        }
-        else if (typeof options.jsonResponse === "string") {
-            openaiTextParam = JSON.parse(options.jsonResponse);
-        }
-        else if (isRecord(options.jsonResponse)) {
-            openaiTextParam = JSON.parse(JSON.stringify(options.jsonResponse));
-            const format = openaiTextParam.format;
-            if (isRecord(format) && typeof format.description === "string") {
-                format.description =
-                    `${format.description}\n\nABSOLUTELY NO UNICODE ALLOWED. ` +
-                        `Only use typeable keyboard characters. Do not try to circumvent this rule ` +
-                        `with escape sequences, backslashes, or other tricks. Use double dashes (--), ` +
-                        `straight quotes (") and single quotes (') instead of em-dashes, en-dashes, ` +
-                        `and curly versions.`.trim();
-            }
-        }
-    }
-    const filteredMessages = messages.filter((message) => {
-        if (!isRecord(message)) {
-            return true;
-        }
-        const role = message.role;
-        const content = message.content;
-        return !(role === "system" &&
-            typeof content === "string" &&
-            content.startsWith("!DATETIME:"));
-    });
-    let preparedMessages = [currentDatetimeSystemMessage(), ...filteredMessages];
-    if (options.systemAnnouncementMessage && options.systemAnnouncementMessage.trim()) {
-        preparedMessages = [
-            { role: "system", content: options.systemAnnouncementMessage.trim() },
-            ...preparedMessages,
-        ];
-    }
-    for (let index = 0; index < retryLimit; index += 1) {
-        let llmReply = "";
-        try {
-            const payload = {
-                model,
-                input: preparedMessages,
-            };
-            if (openaiTextParam) {
-                payload.text = openaiTextParam;
-            }
-            const llmResponse = await openaiClient.responses.create(payload);
-            if (llmResponse.error && options.warningCallback) {
-                options.warningCallback(`ERROR: OpenAI API returned an error: ${llmResponse.error}`);
-            }
-            if (llmResponse.incomplete_details && options.warningCallback) {
-                options.warningCallback(`ERROR: OpenAI API returned incomplete details: ${llmResponse.incomplete_details}`);
-            }
-            llmReply = llmResponse.output_text.trim();
-            if (!options.jsonResponse) {
-                return `${llmReply}`;
-            }
-            return parseFirstJsonValue(llmReply);
-        }
-        catch (error) {
-            if (error instanceof SyntaxError) {
-                failedError = error;
-                if (options.warningCallback) {
-                    options.warningCallback(`JSON decode error:\n\n${error}.\n\nRaw text of LLM Reply:\n${llmReply}\n\nRetrying (attempt ${index + 1} of ${retryLimit}) immediately...`);
-                }
-                continue;
-            }
-            if (isRetryableOpenAIError(error)) {
-                failedError = error;
-                if (options.warningCallback) {
-                    options.warningCallback(`OpenAI API error:\n\n${error}.\n\nRetrying (attempt ${index + 1} of ${retryLimit}) in ${retryBackoffTimeSeconds} seconds...`);
-                }
-                await sleep(retryBackoffTimeSeconds * 1000);
-                continue;
-            }
-            throw error;
-        }
-    }
-    if (failedError) {
-        throw failedError;
-    }
-    throw new Error("Unknown error occurred in gptSubmit");
-}

package/dist/gpt_api/gpt_conversation.d.ts

@@ -1,43 +0,0 @@
-import { type OpenAIClientLike } from "./functions.js";
-export interface ConversationMessage {
-    role: string;
-    content: string;
-}
-export interface GptConversationOptions {
-    openaiClient?: OpenAIClientLike;
-    model?: string;
-}
-export interface SubmitOptions {
-    model?: string;
-    jsonResponse?: boolean | Record<string, unknown> | string;
-}
-export declare class GptConversation extends Array<ConversationMessage> {
-    #private;
-    static get [Symbol.species](): ArrayConstructor;
-    get openaiClient(): OpenAIClientLike | undefined;
-    set openaiClient(value: OpenAIClientLike | undefined);
-    get model(): string | undefined;
-    set model(value: string | undefined);
-    get lastReply(): unknown;
-    set lastReply(value: unknown);
-    constructor(messages?: ConversationMessage[], options?: GptConversationOptions);
-    assignMessages(messages?: ConversationMessage[]): this;
-    clone(): GptConversation;
-    submit(message?: string | Record<string, unknown>, role?: string | null, options?: SubmitOptions): Promise<unknown>;
-    addMessage(role: string, content: unknown): this;
-    addUserMessage(content: unknown): this;
-    addAssistantMessage(content: unknown): this;
-    addSystemMessage(content: unknown): this;
-    addDeveloperMessage(content: unknown): this;
-    submitMessage(role: string, content: unknown): Promise<unknown>;
-    submitUserMessage(content: unknown): Promise<unknown>;
-    submitAssistantMessage(content: unknown): Promise<unknown>;
-    submitSystemMessage(content: unknown): Promise<unknown>;
-    submitDeveloperMessage(content: unknown): Promise<unknown>;
-    getLastMessage(): ConversationMessage | null;
-    getMessagesByRole(role: string): ConversationMessage[];
-    getLastReplyStr(): string;
-    getLastReplyDict(): Record<string, unknown>;
-    getLastReplyDictField(fieldName: string, defaultValue?: unknown): unknown;
-    toDictList(): ConversationMessage[];
-}

package/dist/gpt_api/gpt_conversation.js

@@ -1,146 +0,0 @@
-import { GPT_MODEL_SMART, gptSubmit } from "./functions.js";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-export class GptConversation extends Array {
-    static get [Symbol.species]() {
-        return Array;
-    }
-    #openaiClient;
-    #model;
-    #lastReply = null;
-    get openaiClient() {
-        return this.#openaiClient;
-    }
-    set openaiClient(value) {
-        this.#openaiClient = value;
-    }
-    get model() {
-        return this.#model;
-    }
-    set model(value) {
-        this.#model = value;
-    }
-    get lastReply() {
-        return this.#lastReply;
-    }
-    set lastReply(value) {
-        this.#lastReply = value;
-    }
-    constructor(messages = [], options = {}) {
-        super(...messages);
-        this.#openaiClient = options.openaiClient;
-        this.#model = options.model;
-    }
-    assignMessages(messages) {
-        this.length = 0;
-        if (messages?.length) {
-            this.push(...messages);
-        }
-        return this;
-    }
-    clone() {
-        return new GptConversation(JSON.parse(JSON.stringify([...this])), {
-            openaiClient: this.openaiClient,
-            model: this.model,
-        });
-    }
-    async submit(message, role = "user", options = {}) {
-        if (!this.openaiClient) {
-            throw new Error("OpenAI client is not set. Please provide an OpenAI client.");
-        }
-        const model = options.model || this.model || GPT_MODEL_SMART;
-        let jsonResponse = options.jsonResponse;
-        if (message) {
-            if (isRecord(message)) {
-                if (!jsonResponse && "format" in message) {
-                    jsonResponse = message;
-                }
-                if (!role && typeof message.role === "string") {
-                    role = message.role;
-                }
-                if ("content" in message) {
-                    message = String(message.content ?? "");
-                }
-            }
-            this.addMessage(role || "user", message);
-        }
-        const llmReply = await gptSubmit(this.toDictList(), this.openaiClient, {
-            jsonResponse,
-            model,
-        });
-        this.addAssistantMessage(llmReply);
-        this.lastReply = llmReply;
-        return llmReply;
-    }
-    addMessage(role, content) {
-        let normalizedContent;
-        if (typeof content === "string") {
-            normalizedContent = content;
-        }
-        else if (isRecord(content)) {
-            normalizedContent = JSON.stringify(content, null, 2);
-        }
-        else {
-            normalizedContent = String(content);
-        }
-        this.push({ role, content: normalizedContent });
-        return this;
-    }
-    addUserMessage(content) {
-        return this.addMessage("user", content);
-    }
-    addAssistantMessage(content) {
-        return this.addMessage("assistant", content);
-    }
-    addSystemMessage(content) {
-        return this.addMessage("system", content);
-    }
-    addDeveloperMessage(content) {
-        return this.addMessage("developer", content);
-    }
-    async submitMessage(role, content) {
-        this.addMessage(role, content);
-        return this.submit();
-    }
-    async submitUserMessage(content) {
-        this.addUserMessage(content);
-        return this.submit();
-    }
-    async submitAssistantMessage(content) {
-        this.addAssistantMessage(content);
-        return this.submit();
-    }
-    async submitSystemMessage(content) {
-        this.addSystemMessage(content);
-        return this.submit();
-    }
-    async submitDeveloperMessage(content) {
-        this.addDeveloperMessage(content);
-        return this.submit();
-    }
-    getLastMessage() {
-        return this.length ? this[this.length - 1] : null;
-    }
-    getMessagesByRole(role) {
-        return this.filter((message) => message.role === role);
-    }
-    getLastReplyStr() {
-        return typeof this.lastReply === "string" ? this.lastReply : "";
-    }
-    getLastReplyDict() {
-        if (!isRecord(this.lastReply)) {
-            return {};
-        }
-        return JSON.parse(JSON.stringify(this.lastReply));
-    }
-    getLastReplyDictField(fieldName, defaultValue = null) {
-        if (!isRecord(this.lastReply)) {
-            return null;
-        }
-        return this.lastReply[fieldName] ?? defaultValue;
-    }
-    toDictList() {
-        return [...this];
-    }
-}

package/dist/gpt_api/json_schema_format.d.ts

@@ -1,18 +0,0 @@
-export declare const JSON_INTEGER: unique symbol;
-export declare const JSON_NUMBER: unique symbol;
-export declare const JSON_STRING: StringConstructor;
-export declare const JSON_BOOLEAN: BooleanConstructor;
-export interface JSONSchemaFormatOptions {
-    name?: string;
-    description?: string;
-}
-export interface JSONSchemaFormatResult {
-    format: {
-        type: "json_schema";
-        strict: true;
-        name?: string;
-        description?: string;
-        schema: Record<string, unknown>;
-    };
-}
-export declare function JSONSchemaFormat(schema: unknown, options?: JSONSchemaFormatOptions): JSONSchemaFormatResult;