mdi-llmkit 1.1.0 → 1.1.3

package/README.md

@@ -76,7 +76,7 @@ import { jsonSurgery } from 'mdi-llmkit/jsonSurgery';
 - It supports optional schema guidance and key-skipping for model-visible context.
 - It supports validation/progress callbacks and soft iteration/time limits.
 
-## `compareItemLists` (comparison)
+## `compareItemLists` (semanticMatch)
 
 `compareItemLists` performs a semantic diff between a "before" list and an "after" list,
 including LLM-assisted rename/add/remove decisions.
@@ -106,7 +106,7 @@ import {
   compareItemLists,
   ItemComparisonResult,
   type OnComparingItemCallback,
-} from 'mdi-llmkit/comparison';
+} from 'mdi-llmkit/semanticMatch';
 
 const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 

package/dist/src/semanticMatch/compareLists.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Semantic comparison for before/after item lists.
+ *
+ * This module compares two lists that represent the same domain at different points
+ * in time (for example, before and after a migration) and classifies items as:
+ * - unchanged,
+ * - renamed,
+ * - removed, or
+ * - added.
+ *
+ * It is designed for cases where exact string comparison is not sufficient because
+ * names may change while meaning stays the same.
+ */
+import { OpenAI } from 'openai';
+import { SemanticItem } from './semanticItem.js';
+/**
+ * Final classification of an item during comparison.
+ */
+export declare enum ItemComparisonClassification {
+    /** Item existed in "before" and is considered deleted in "after". */
+    Removed = "removed",
+    /** Item exists in "after" and is considered newly introduced. */
+    Added = "added",
+    /** Item from "before" was matched to a different name in "after". */
+    Renamed = "renamed",
+    /** Item is treated as unchanged or unresolved for downstream purposes. */
+    Unchanged = "unchanged"
+}
+export declare const ItemComparisonResult: typeof ItemComparisonClassification;
+export type ItemComparisonResult = {
+    item: SemanticItem;
+    classification: ItemComparisonClassification;
+    newName: string | undefined;
+};
+/**
+ * Compares two lists of items and classifies each item from the "before" list as removed,
+ * renamed, or unchanged based on whether it has a semantic match in the "after" list.
+ * Any items in the "after" list that don't match to an item in the "before" list are
+ * classified as added.
+ * @param before - The list of items before the changes.
+ * @param after - The list of items after the changes.
+ * @param explanation Optional explanation that provides context for the comparison, e.g.
+ * a description of the items or the nature of the changes.
+ * @returns An array of item comparison results. This includes all items from the "before"
+ * list with their classification (removed/renamed/unchanged), and any unmatched items from
+ * the "after" list classified as added.
+ */
+export declare const compareItemLists: (openaiClient: OpenAI, listBefore: SemanticItem[], listAfter: SemanticItem[], explanation?: string) => Promise<ItemComparisonResult[]>;

package/dist/src/semanticMatch/compareLists.js

@@ -0,0 +1,87 @@
+/**
+ * Semantic comparison for before/after item lists.
+ *
+ * This module compares two lists that represent the same domain at different points
+ * in time (for example, before and after a migration) and classifies items as:
+ * - unchanged,
+ * - renamed,
+ * - removed, or
+ * - added.
+ *
+ * It is designed for cases where exact string comparison is not sufficient because
+ * names may change while meaning stays the same.
+ */
+import { areItemsEqual, getItemName } from './semanticItem.js';
+import { findSemanticMatch } from './find.js';
+/**
+ * Final classification of an item during comparison.
+ */
+export var ItemComparisonClassification;
+(function (ItemComparisonClassification) {
+    /** Item existed in "before" and is considered deleted in "after". */
+    ItemComparisonClassification["Removed"] = "removed";
+    /** Item exists in "after" and is considered newly introduced. */
+    ItemComparisonClassification["Added"] = "added";
+    /** Item from "before" was matched to a different name in "after". */
+    ItemComparisonClassification["Renamed"] = "renamed";
+    /** Item is treated as unchanged or unresolved for downstream purposes. */
+    ItemComparisonClassification["Unchanged"] = "unchanged";
+})(ItemComparisonClassification || (ItemComparisonClassification = {}));
+export const ItemComparisonResult = ItemComparisonClassification;
+/**
+ * Compares two lists of items and classifies each item from the "before" list as removed,
+ * renamed, or unchanged based on whether it has a semantic match in the "after" list.
+ * Any items in the "after" list that don't match to an item in the "before" list are
+ * classified as added.
+ * @param before - The list of items before the changes.
+ * @param after - The list of items after the changes.
+ * @param explanation Optional explanation that provides context for the comparison, e.g.
+ * a description of the items or the nature of the changes.
+ * @returns An array of item comparison results. This includes all items from the "before"
+ * list with their classification (removed/renamed/unchanged), and any unmatched items from
+ * the "after" list classified as added.
+ */
+export const compareItemLists = async (openaiClient, listBefore, listAfter, explanation) => {
+    // We're going to be removing items from the "after" list as we match them,
+    // so we make a copy of it to avoid mutating the original array.
+    listAfter = [...listAfter];
+    const retval = [];
+    for (const itemBefore of listBefore) {
+        const indexMatchedInAfter = await findSemanticMatch(openaiClient, listAfter, itemBefore, explanation);
+        if (indexMatchedInAfter === -1) {
+            // No good match found in "after" list, so this item is probably removed.
+            retval.push({
+                item: itemBefore,
+                classification: ItemComparisonClassification.Removed,
+                newName: undefined,
+            });
+            continue;
+        }
+        const itemAfter = listAfter[indexMatchedInAfter];
+        if (areItemsEqual(itemBefore, itemAfter)) {
+            retval.push({
+                item: itemBefore,
+                classification: ItemComparisonClassification.Unchanged,
+                newName: undefined,
+            });
+        }
+        else {
+            retval.push({
+                item: itemBefore,
+                classification: ItemComparisonClassification.Renamed,
+                newName: getItemName(itemAfter),
+            });
+        }
+        // Remove the matched item from the "after" list so it can't be matched again.
+        listAfter.splice(indexMatchedInAfter, 1);
+    }
+    // All of the remaining items in the "after" list are considered added.
+    for (const itemAfter of listAfter) {
+        retval.push({
+            item: itemAfter,
+            classification: ItemComparisonClassification.Added,
+            newName: undefined,
+        });
+    }
+    return retval;
+};

package/dist/src/semanticMatch/find.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Semantic match finder for migration-style item lists.
+ *
+ * This module provides a helper that determines whether a "test item" is already present
+ * in an existing list, even when names are different. In this context, a semantic match
+ * means two labels point to the same underlying concept (for example, renamed fields,
+ * wording changes, or synonyms).
+ *
+ * Matching strategy:
+ * 1) Check for exact name equality.
+ * 2) If no exact match exists, use an LLM to infer conceptual equivalence.
+ *
+ * The exported function returns the index of the first matching list item when a match
+ * is found, or `-1` when no sufficiently similar item exists.
+ */
+import { OpenAI } from 'openai';
+import { SemanticItem } from './semanticItem.js';
+/**
+ * Finds the best semantic match for a test item within a list of items.
+ *
+ * A semantic match means two items represent the same underlying concept even if their
+ * names differ (for example, due to renaming, wording changes, or synonyms).
+ *
+ * The function first checks for an exact name match and returns its index immediately
+ * if found.
+ * If no exact match exists, it asks the LLM to decide whether the test item is represented
+ * in the list under a different name and returns the index of the first matching list item,
+ * or `-1` when no good semantic match is found.
+ *
+ * @param openaiClient An instance of the OpenAI client to use for LLM interactions.
+ * @param itemlist The list of strings/items to compare.
+ * @param itemToFind The item for which we want to find a semantic match in the list.
+ * @param explanation Optional explanation that provides context for the comparison, e.g.
+ * a description of the items or the nature of the changes.
+ * @returns The index of the first matching item from the list, or `-1` if no good match
+ * is found.
+ */
+export declare const findSemanticMatch: (openaiClient: OpenAI, itemlist: SemanticItem[], itemToFind: SemanticItem, explanation?: string) => Promise<number>;

package/dist/src/semanticMatch/find.js

@@ -0,0 +1,134 @@
+/**
+ * Semantic match finder for migration-style item lists.
+ *
+ * This module provides a helper that determines whether a "test item" is already present
+ * in an existing list, even when names are different. In this context, a semantic match
+ * means two labels point to the same underlying concept (for example, renamed fields,
+ * wording changes, or synonyms).
+ *
+ * Matching strategy:
+ * 1) Check for exact name equality.
+ * 2) If no exact match exists, use an LLM to infer conceptual equivalence.
+ *
+ * The exported function returns the index of the first matching list item when a match
+ * is found, or `-1` when no sufficiently similar item exists.
+ */
+import { areItemsEqual, itemToPromptString, } from './semanticItem.js';
+import { GptConversation } from '../gptApi/gptConversation.js';
+import { JSONSchemaFormat } from '../gptApi/jsonSchemaFormat.js';
+/**
+ * Finds the best semantic match for a test item within a list of items.
+ *
+ * A semantic match means two items represent the same underlying concept even if their
+ * names differ (for example, due to renaming, wording changes, or synonyms).
+ *
+ * The function first checks for an exact name match and returns its index immediately
+ * if found.
+ * If no exact match exists, it asks the LLM to decide whether the test item is represented
+ * in the list under a different name and returns the index of the first matching list item,
+ * or `-1` when no good semantic match is found.
+ *
+ * @param openaiClient An instance of the OpenAI client to use for LLM interactions.
+ * @param itemlist The list of strings/items to compare.
+ * @param itemToFind The item for which we want to find a semantic match in the list.
+ * @param explanation Optional explanation that provides context for the comparison, e.g.
+ * a description of the items or the nature of the changes.
+ * @returns The index of the first matching item from the list, or `-1` if no good match
+ * is found.
+ */
+export const findSemanticMatch = async (openaiClient, itemlist, itemToFind, explanation) => {
+    // First check if there's an exact match for the item in the list.
+    // If so, we can skip the LLM and just return that.
+    for (let i = 0; i < itemlist.length; i++) {
+        const item = itemlist[i];
+        if (areItemsEqual(item, itemToFind)) {
+            return i;
+        }
+    }
+    const convo = new GptConversation([], { openaiClient });
+    convo.addSystemMessage(`
+You are a data analyst who has been hired to try to preserve the integrity of a list of
+data items. The user will show you a list of items from a data migration, followed by 
+a "test item". Your job is to determine whether the test item is already present in
+the list (but maybe under a different name), or whether it is not present in the list
+at all.
+
+We've already determined that the test item does not have an exact name match in the list,
+but it might have been renamed or expressed in a different way. 
+
+Let me give you a few examples of what I mean by this:
+
+- Imagine that the list is ["Customer ID", "Order Date", "Total Amount"], and the test item 
+    is "Client Identifier". Then you'd return "Customer ID".
+
+- Imagine that the list is ["Customer ID", "Order Date", "Total Amount"], and the test item
+    is "Date of Order". Then you'd return "Order Date".
+
+- Imagine that the list is ["Customer ID", "Order Date", "Total Amount"], and the test item
+    is "Product Name". Then you'd return null, because none of the items in the list are
+    semantically similar to "Product Name".
+
+- Imagine that the list is ["Dragonfly", "Butterfly", "Firefly"], and the test item is
+    "Lightning Bug". Then you'd return "Firefly".
+    
+- Imagine that the list is ["Dragonfly", "Butterfly", "Firefly"], and the test item is
+    "Spider". Then you'd return null, because none of the items in the list are 
+    semantically similar to "Spider".
+`);
+    if (explanation) {
+        convo.addSystemMessage(`
+Here is some additional context that may help you make better decisions about which items
+have been renamed versus removed/added:
+
+${explanation}
+`);
+    }
+    let sList = '';
+    for (let iItem = 0; iItem < itemlist.length; iItem++) {
+        const item = itemlist[iItem];
+        sList += `- ITEM #${iItem + 1}. ${itemToPromptString(item)}\n`;
+    }
+    convo.addUserMessage(`
+Here is the list of items:
+
+${sList}
+
+And here is the test item to compare against that list:
+
+- ${itemToPromptString(itemToFind)}
+`);
+    await convo.submit(undefined, undefined, {
+        jsonResponse: JSONSchemaFormat('list_comparison_find_potentially_renamed_item', {
+            discussion: [
+                String,
+                'Your reasoning process as you compare the test item to the items in the list. ' +
+                    'This is for debugging purposes and will not be parsed by any downstream logic, ' +
+                    'but please provide as much detail as possible about your thinking here, ' +
+                    'as it will help us understand your decision-making process.',
+            ],
+            is_testitem_in_list: [
+                Boolean,
+                'Whether the test item is present in the list.',
+            ],
+            item_number_in_list: [
+                Number,
+                `The item number (as indicated by "ITEM #") of the item that you've identified as ` +
+                    `matching the test item. If you don't think any item in the list matches the ` +
+                    `test item, then set this to -1.`,
+            ],
+        }),
+    });
+    const isTestItemInList = convo.getLastReplyDictField('is_testitem_in_list');
+    const itemNumberInList = convo.getLastReplyDictField('item_number_in_list');
+    if (!isTestItemInList) {
+        return -1;
+    }
+    if (!Number.isInteger(itemNumberInList)) {
+        return -1;
+    }
+    const index = itemNumberInList - 1;
+    if (index < 0 || index >= itemlist.length) {
+        return -1;
+    }
+    return index;
+};

package/dist/src/{comparison → semanticMatch}/index.d.ts

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

package/dist/src/{comparison → semanticMatch}/index.js

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

package/dist/src/semanticMatch/semanticItem.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared item primitives and helpers used by semantic list comparison.
+ *
+ * This module intentionally focuses on item-level behavior:
+ * - `SemanticItem` defines the accepted item shape (`string` or `{ name, description? }`).
+ * - `getItemName` normalizes an item to its comparable name.
+ * - `itemToPromptString` formats an item for prompt text, including optional details.
+ * - `compareItems` provides case-insensitive ordering by item name.
+ * - `areItemsEqual` provides equality checks across comparable item content.
+ *
+ * Matching orchestration (removed/added/renamed classification) is implemented in
+ * higher-level modules and consumes these utilities.
+ */
+/**
+ * Item shape accepted by `compareItemLists` for semantic comparison.
+ *
+ * - A raw string is treated as the item's comparable name.
+ * - An object uses `name` as the comparable value and may include optional
+ *   `description` to provide additional LLM context.
+ */
+export type SemanticItem = string | {
+    name: string;
+    description?: string;
+};
+/**
+ * Returns the comparable name for a list item.
+ * @param item The item to extract the name from.
+ * @returns The name of the item, which is used for comparison and matching.
+ */
+export declare const getItemName: (item: SemanticItem) => string;
+/**
+ * Returns the description of a list item, if available and non-redundant with the name.
+ * If the item is a string or if the description is missing or effectively the same as the name,
+ * this function returns `undefined`.
+ * @param item The item to extract the description from.
+ * @returns The description of the item, or `undefined` if not available or redundant.
+ */
+export declare const getItemDescription: (item: SemanticItem) => string | undefined;
+/**
+ * Formats a list item for prompt inclusion, including optional description context.
+ * The output is a string that starts with "- " followed by the item name, and if a
+ * description is provided and is not redundant with the name, it includes the description
+ * in parentheses. The item name and description are JSON-stringified to prevent formatting
+ * issues in the prompt (e.g. with newlines or special characters).
+ * @param item The item to format for the prompt.
+ * @returns A string representation of the item suitable for inclusion in the prompt.
+ */
+export declare const itemToPromptString: (item: SemanticItem) => string;
+/**
+ * Sort comparator for list items.
+ *
+ * Ordering behavior:
+ * 1) Compare names case-insensitively after trimming leading/trailing whitespace.
+ * 2) If names are equal, compare non-redundant descriptions case-insensitively
+ *    as a tie-breaker. We only compare descriptions when both items have a
+ *    non-redundant description.
+ */
+export declare const compareItems: (a: SemanticItem, b: SemanticItem) => number;
+/**
+ * Equality check for two items.
+ *
+ * Equality uses the same semantics as `compareItems`:
+ * - names are compared case-insensitively after trimming;
+ * - when names tie, non-redundant descriptions are compared
+ *   case-insensitively after trimming.
+ * @param a The first item to compare.
+ * @param b The second item to compare.
+ * @returns `true` if the items are equal under comparator semantics, `false` otherwise.
+ */
+export declare const areItemsEqual: (a: SemanticItem, b: SemanticItem) => boolean;
+/**
+ * Removes an item from a list based on full item equivalence.
+ * @param itemList The list of items to remove from.
+ * @param itemToRemove The item to remove from the list. Any item equal to this item
+ * under `areItemsEqual` semantics will be removed.
+ * @returns A new list with the specified item removed.
+ */
+export declare const removeItemFromList: (itemList: SemanticItem[], itemToRemove: SemanticItem) => SemanticItem[];

package/dist/src/semanticMatch/semanticItem.js

@@ -0,0 +1,110 @@
+/**
+ * Shared item primitives and helpers used by semantic list comparison.
+ *
+ * This module intentionally focuses on item-level behavior:
+ * - `SemanticItem` defines the accepted item shape (`string` or `{ name, description? }`).
+ * - `getItemName` normalizes an item to its comparable name.
+ * - `itemToPromptString` formats an item for prompt text, including optional details.
+ * - `compareItems` provides case-insensitive ordering by item name.
+ * - `areItemsEqual` provides equality checks across comparable item content.
+ *
+ * Matching orchestration (removed/added/renamed classification) is implemented in
+ * higher-level modules and consumes these utilities.
+ */
+/**
+ * Returns the comparable name for a list item.
+ * @param item The item to extract the name from.
+ * @returns The name of the item, which is used for comparison and matching.
+ */
+export const getItemName = (item) => {
+    return typeof item === 'string' ? item : item.name;
+};
+/**
+ * Returns the description of a list item, if available and non-redundant with the name.
+ * If the item is a string or if the description is missing or effectively the same as the name,
+ * this function returns `undefined`.
+ * @param item The item to extract the description from.
+ * @returns The description of the item, or `undefined` if not available or redundant.
+ */
+export const getItemDescription = (item) => {
+    if (typeof item === 'string') {
+        return undefined;
+    }
+    if (!item.description) {
+        return undefined;
+    }
+    // If the description is the same as the name (ignoring case and whitespace),
+    // then it's not really providing any additional context, so we can ignore it.
+    if (item.description.trim().toLowerCase() === item.name.trim().toLowerCase()) {
+        return undefined;
+    }
+    return item.description;
+};
+/**
+ * Formats a list item for prompt inclusion, including optional description context.
+ * The output is a string that starts with "- " followed by the item name, and if a
+ * description is provided and is not redundant with the name, it includes the description
+ * in parentheses. The item name and description are JSON-stringified to prevent formatting
+ * issues in the prompt (e.g. with newlines or special characters).
+ * @param item The item to format for the prompt.
+ * @returns A string representation of the item suitable for inclusion in the prompt.
+ */
+export const itemToPromptString = (item) => {
+    let s = `- ${JSON.stringify(getItemName(item))}`;
+    const description = getItemDescription(item);
+    if (description) {
+        s += ` (details: ${JSON.stringify(description)})`;
+    }
+    return s;
+};
+/**
+ * Sort comparator for list items.
+ *
+ * Ordering behavior:
+ * 1) Compare names case-insensitively after trimming leading/trailing whitespace.
+ * 2) If names are equal, compare non-redundant descriptions case-insensitively
+ *    as a tie-breaker. We only compare descriptions when both items have a
+ *    non-redundant description.
+ */
+export const compareItems = (a, b) => {
+    const nameA = getItemName(a).trim().toLowerCase();
+    const nameB = getItemName(b).trim().toLowerCase();
+    const byName = nameA.localeCompare(nameB);
+    if (byName !== 0) {
+        return byName;
+    }
+    const descA = (getItemDescription(a) ?? '').trim().toLowerCase();
+    const descB = (getItemDescription(b) ?? '').trim().toLowerCase();
+    // In order to compare descriptions, both items should have a description.
+    // If only one item has a description, we don't bother comparing the
+    // description field.
+    if (!descA || !descB) {
+        return 0;
+    }
+    // If we have two descriptions, we can use them as a tie-breaker.
+    return descA.localeCompare(descB);
+};
+/**
+ * Equality check for two items.
+ *
+ * Equality uses the same semantics as `compareItems`:
+ * - names are compared case-insensitively after trimming;
+ * - when names tie, non-redundant descriptions are compared
+ *   case-insensitively after trimming.
+ * @param a The first item to compare.
+ * @param b The second item to compare.
+ * @returns `true` if the items are equal under comparator semantics, `false` otherwise.
+ */
+export const areItemsEqual = (a, b) => {
+    return compareItems(a, b) === 0;
+};
+/**
+ * Removes an item from a list based on full item equivalence.
+ * @param itemList The list of items to remove from.
+ * @param itemToRemove The item to remove from the list. Any item equal to this item
+ * under `areItemsEqual` semantics will be removed.
+ * @returns A new list with the specified item removed.
+ */
+export const removeItemFromList = (itemList, itemToRemove) => {
+    return itemList.filter(item => !areItemsEqual(item, itemToRemove));
+};