mdi-llmkit 0.1.0 → 1.0.1

package/dist/src/comparison/index.d.ts

@@ -0,0 +1 @@
+export * from './compareLists.js';

package/dist/src/comparison/index.js

@@ -0,0 +1 @@
+export * from './compareLists.js';

package/dist/src/gptApi/functions.d.ts

@@ -0,0 +1,21 @@
+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: any, options?: any) => 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/src/gptApi/functions.js

@@ -0,0 +1,154 @@
+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));
+}
+/**
+ * OpenAI's API, even when called with a JSON schema, will often return text that is not
+ * valid JSON. It's often because the model will add extra text after the end of its valid
+ * JSON response. E.g. instead of `{"foo":"bar"}`, it will sometimes return
+ * `{"foo":"bar"}{"baz":"quux"}`.
+ *
+ * We intentionally do not implement a custom JSON parser here. Instead:
+ * 1) Try to parse the full text first (fast path, most responses).
+ * 2) If that fails, scan prefixes from start to end and let JSON.parse decide validity.
+ *
+ * This keeps JSON semantics delegated to the platform parser while still recovering from
+ * trailing junk in model output.
+ *
+ * @param input The text to parse.
+ * @returns The first valid JSON value found at the start of the input text.
+ * @throws {SyntaxError} If no valid JSON prefix exists.
+ */
+function parseFirstJsonValue(input) {
+    const text = input.trimStart();
+    if (!text) {
+        throw new SyntaxError("Unexpected end of JSON input");
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        for (let end = 1; end <= text.length; end += 1) {
+            try {
+                return JSON.parse(text.slice(0, end));
+            }
+            catch {
+                // Keep scanning until we find a valid JSON prefix.
+            }
+        }
+    }
+    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/src/gptApi/gptConversation.d.ts

@@ -0,0 +1,43 @@
+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/src/gptApi/gptConversation.js

@@ -0,0 +1,146 @@
+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/src/gptApi/index.d.ts

@@ -0,0 +1,3 @@
+export * from './functions.js';
+export * from './gptConversation.js';
+export * from './jsonSchemaFormat.js';

package/dist/src/gptApi/index.js

@@ -0,0 +1,3 @@
+export * from './functions.js';
+export * from './gptConversation.js';
+export * from './jsonSchemaFormat.js';

package/dist/src/gptApi/jsonSchemaFormat.d.ts

@@ -0,0 +1,14 @@
+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 JSONSchemaFormatResult extends Record<string, unknown> {
+    format: {
+        type: 'json_schema';
+        strict: true;
+        name?: string;
+        description?: string;
+        schema: Record<string, unknown>;
+    };
+}
+export declare function JSONSchemaFormat(name: string, schema: unknown, description?: string): JSONSchemaFormatResult;

package/dist/src/gptApi/jsonSchemaFormat.js

@@ -0,0 +1,198 @@
+export const JSON_INTEGER = Symbol('JSON_INTEGER');
+export const JSON_NUMBER = Symbol('JSON_NUMBER');
+export const JSON_STRING = String;
+export const JSON_BOOLEAN = Boolean;
+const TYPEMAP = new Map([
+    [JSON_STRING, 'string'],
+    [JSON_INTEGER, 'integer'],
+    [JSON_NUMBER, 'number'],
+    [JSON_BOOLEAN, 'boolean'],
+    [String, 'string'],
+    [Boolean, 'boolean'],
+    [BigInt, 'integer'],
+    [Number, 'number'],
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === 'string'));
+}
+function isNumericRangeArray(value) {
+    if (!Array.isArray(value) || value.length !== 2) {
+        return false;
+    }
+    const [min, max] = value;
+    const minValid = min === null || typeof min === 'number';
+    const maxValid = max === null || typeof max === 'number';
+    return (minValid && maxValid && (typeof min === 'number' || typeof max === 'number'));
+}
+function isTupleMetadataArray(value) {
+    if (!Array.isArray(value) || value.length < 2) {
+        return false;
+    }
+    if (isStringArray(value)) {
+        return false;
+    }
+    return value.some((item) => typeof item === 'string' || isNumericRangeArray(item));
+}
+function inferPrimitiveType(schemaValue) {
+    const direct = TYPEMAP.get(schemaValue);
+    if (direct) {
+        return direct;
+    }
+    if (typeof schemaValue === 'string') {
+        return 'string';
+    }
+    if (typeof schemaValue === 'boolean') {
+        return 'boolean';
+    }
+    if (typeof schemaValue === 'bigint') {
+        return 'integer';
+    }
+    if (typeof schemaValue === 'number') {
+        return Number.isInteger(schemaValue) ? 'integer' : 'number';
+    }
+    return null;
+}
+function convertSchemaRecursive(subschema) {
+    let subschemaDescription = '';
+    let subschemaEnum = [];
+    let subschemaNumrange = [null, null];
+    let subschemaValue = subschema;
+    if (isTupleMetadataArray(subschema)) {
+        for (const item of subschema) {
+            if (!item) {
+                subschemaValue = item;
+                continue;
+            }
+            if (typeof item === 'string') {
+                subschemaDescription = item;
+                continue;
+            }
+            if (isStringArray(item) && item.length >= 2) {
+                subschemaEnum = item;
+                continue;
+            }
+            if (isNumericRangeArray(item)) {
+                subschemaNumrange = item;
+                continue;
+            }
+            subschemaValue = item;
+        }
+    }
+    if ((Array.isArray(subschemaValue) && isTupleMetadataArray(subschemaValue)) ||
+        (Array.isArray(subschemaValue) && subschemaValue.length === 0)) {
+        if (subschemaEnum.length > 0) {
+            subschemaValue = JSON_STRING;
+        }
+        const [nr0, nr1] = subschemaNumrange;
+        if (nr0 !== null || nr1 !== null) {
+            if ((typeof nr0 === 'number' && !Number.isInteger(nr0)) ||
+                (typeof nr1 === 'number' && !Number.isInteger(nr1))) {
+                subschemaValue = JSON_NUMBER;
+            }
+            else {
+                subschemaValue = JSON_INTEGER;
+            }
+        }
+    }
+    const result = {};
+    if (isRecord(subschemaValue)) {
+        result.type = 'object';
+        if (subschemaDescription) {
+            result.description = subschemaDescription;
+        }
+        result.additionalProperties = false;
+        const keys = Object.keys(subschemaValue);
+        result.required = keys;
+        const properties = {};
+        for (const [key, value] of Object.entries(subschemaValue)) {
+            if (typeof value === 'string') {
+                properties[key] = { type: 'string', description: value };
+            }
+            else {
+                properties[key] = convertSchemaRecursive(value);
+            }
+        }
+        result.properties = properties;
+    }
+    else if (Array.isArray(subschemaValue)) {
+        if (subschemaValue.length >= 2 && isStringArray(subschemaValue)) {
+            result.type = 'string';
+            subschemaEnum = subschemaValue;
+        }
+        else {
+            result.type = 'array';
+            if (subschemaDescription) {
+                result.description = subschemaDescription;
+            }
+            if (subschemaNumrange[0] !== null) {
+                result.minItems = subschemaNumrange[0];
+            }
+            if (subschemaNumrange[1] !== null) {
+                result.maxItems = subschemaNumrange[1];
+            }
+            const arrayExemplar = subschemaValue[0];
+            if (typeof arrayExemplar === 'string') {
+                result.items = { type: 'string', description: arrayExemplar };
+            }
+            else {
+                result.items = convertSchemaRecursive(arrayExemplar);
+            }
+        }
+    }
+    else {
+        const primitiveType = inferPrimitiveType(subschemaValue);
+        if (!primitiveType) {
+            throw new Error(`Unrecognized type for schema value: ${String(subschemaValue)}`);
+        }
+        result.type = primitiveType;
+        if (subschemaDescription) {
+            result.description = subschemaDescription;
+        }
+    }
+    if (subschemaEnum.length) {
+        result.enum = subschemaEnum;
+    }
+    if (result.type === 'integer' || result.type === 'number') {
+        if (subschemaNumrange[0] !== null) {
+            result.minimum = subschemaNumrange[0];
+        }
+        if (subschemaNumrange[1] !== null) {
+            result.maximum = subschemaNumrange[1];
+        }
+    }
+    return result;
+}
+export function JSONSchemaFormat(name, schema, description) {
+    const result = {
+        format: {
+            type: 'json_schema',
+            strict: true,
+            name,
+            schema: {
+                type: 'object',
+                properties: {},
+                required: [],
+                additionalProperties: false,
+            },
+        },
+    };
+    if (description) {
+        result.format.description = description;
+    }
+    let converted = convertSchemaRecursive(schema);
+    if (converted.type !== 'object') {
+        converted = {
+            type: 'object',
+            required: [name],
+            additionalProperties: false,
+            properties: {
+                [name]: converted,
+            },
+        };
+    }
+    result.format.schema = converted;
+    return result;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./gptApi/functions.js";
+export * from "./gptApi/gptConversation.js";
+export * from "./gptApi/jsonSchemaFormat.js";

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export * from "./gptApi/functions.js";
+export * from "./gptApi/gptConversation.js";
+export * from "./gptApi/jsonSchemaFormat.js";

package/dist/src/jsonSurgery/jsonSurgery.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `jsonSurgery` performs iterative, AI-guided edits to a JSON-compatible object.
+ *
+ * The module exposes:
+ * - {@link jsonSurgery}: the main entry point that applies requested modifications.
+ * - {@link JSONSurgeryOptions}: callbacks and limits for validation, progress, and retries.
+ * - {@link JSONSurgeryError}: enriched error type that includes the last object state.
+ *
+ * High-level flow:
+ * 1. Deep-copy the input object (the original is never mutated).
+ * 2. Send the current object state plus user instructions to the model.
+ * 3. Receive one or more structured operations targeting JSON paths.
+ * 4. Apply operations and continue iteratively until validation succeeds.
+ *
+ * Supported operation types include assign, append, insert, delete, and rename.
+ * Values are transferred through constrained JSON schemas so the model can express
+ * primitives, objects, and arrays safely in a structured format.
+ *
+ * Callers can provide:
+ * - `schemaDescription` to describe expected object shape/constraints,
+ * - `skippedKeys` to hide sensitive or noisy fields from model context,
+ * - `onValidateBeforeReturn` to enforce app-specific validation,
+ * - `onWorkInProgress` for per-iteration monitoring/intervention,
+ * - `giveUpAfterSeconds` / `giveUpAfterIterations` as soft stop conditions.
+ */
+import { OpenAI } from 'openai';
+/**
+ * Optional configuration for {@link jsonSurgery}.
+ * @property schemaDescription Optional schema description for the JSON object. This can be written
+ * in JSON Schema format, or as a textual explanation. It's passed as a string to the AI and has
+ * no direct enforcement semantics.
+ * @property skippedKeys Optional array of key names to skip/ignore in the AI-visible JSON. This
+ * is useful for omitting large or sensitive fields (IDs, timestamps, binary data, etc.) that are
+ * often irrelevant to the requested modifications.
+ * @property onValidateBeforeReturn Optional callback that validates and/or corrects the object before
+ * final return. It receives the current object and resolves to:
+ * - objCorrected: a corrected object to continue with
+ * - errors: lingering validation errors that still need to be addressed
+ * @property onWorkInProgress Optional callback that's called after each iteration with the
+ * current state of the object. Useful for logging or monitoring progress. Can optionally return
+ * a promise that resolves into a modified version of the object, in case the caller wants to
+ * intervene or adjust the object mid-process. onWorkInProgress is a good place to implement
+ * custom logging, metrics, or even dynamic adjustments to the object during processing. It's also
+ * a place from whence you can throw an exception if needed to abort processing.
+ * @property giveUpAfterSeconds Optional soft-limit for total processing time, in seconds.
+ * @property giveUpAfterIterations Optional soft-limit for iteration count.
+ *
+ * If `objCorrected` is returned, that corrected object is used.
+ * If `errors` is missing or empty, the object is treated as valid.
+ */
+export type JSONSurgeryOptions = {
+    schemaDescription?: string;
+    skippedKeys?: string[];
+    onValidateBeforeReturn?: (obj: any) => Promise<{
+        objCorrected?: any;
+        errors?: string[];
+    } | undefined>;
+    onWorkInProgress?: (obj: any) => Promise<any | undefined>;
+    giveUpAfterSeconds?: number;
+    giveUpAfterIterations?: number;
+};
+/**
+ * Error type reserved for failures from {@link jsonSurgery}.
+ * `obj` contains the object being modified, captured in whatever state it was
+ * left in at the moment the exception was thrown.
+ */
+export declare class JSONSurgeryError extends Error {
+    obj: any;
+    constructor(message: string, obj: any, options?: ErrorOptions);
+}
+/**
+ * Modifies a JSON object based on modification instructions using OpenAI's API.
+ * Does NOT modify the original object in place; instead, works with a copy and returns
+ * the modified copy.
+ * @param openaiClient The OpenAI client to use for modifications
+ * @param obj The JSON object to modify
+ * @param modificationInstructions Instructions describing the modifications to apply
+ * @param options Optional configuration object. See {@link JSONSurgeryOptions}.
+ * @returns A copy of the original object, modified according to the instructions.
+ */
+export declare const jsonSurgery: (openaiClient: OpenAI, obj: any, modificationInstructions: string, options?: JSONSurgeryOptions) => Promise<any>;